bugGNU Octave - Bugs: bug #53006, GUI Documentation Browser displays...


bug #53006: GUI Documentation Browser displays Index chapters of manual poorly

Submitted by:  Rik <rik5>
Submitted on:  Mon 29 Jan 2018 10:12:23 PM UTC  
Category:  GUI Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Feature Request
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  Closed
Release:  dev Operating System:  Any

Add a New Comment (Rich Markup)

You are not logged in

Please log in, so followups can be emailed to you.


( Jump to the original submission)

Tue 13 Nov 2018 04:27:58 PM UTC, comment #127: 

I also don't see a straightforward solution to having the highlighting not extended to the right edge.  Marking this bug as fixed and closing report.

Rik <rik5>
Project Administrator
Tue 13 Nov 2018 10:02:09 AM UTC, comment #126: 

I don't think QTextBrowser supports any css directive that would help us format the example boxes width. See http://doc.qt.io/archives/qt-4.8/richtext-html-subset.html#css-properties

Note that when using a web browser to view the html doc, the width of example blocks (and regular paragraphs) is better handled. So the key point seams to be using a proper web browser widget instead of the limited QTextBrowser widget.

Pantxo Diribarne <pantxo>
Project Member
Tue 13 Nov 2018 08:44:39 AM UTC, comment #125: 

I have nothing to complain. I can now play with the default branch without the annoying dialogs :) Thanks!

However, there was some discussion about the help browser and formatting, see #comment117 and below. I do not know if this is still relevant.


Sebastian <sschoeps>
Tue 13 Nov 2018 01:06:18 AM UTC, comment #124: 

I checked in the change to disable the Qt warning dialog about missing Qt help files if Octave was configured with --disable-docs (https://hg.savannah.gnu.org/hgweb/octave/rev/673b1af42143).

Also, I was finally able to reproduce the warning messages you saw.

Is there anything else to do for this bug report?

Rik <rik5>
Project Administrator
Mon 12 Nov 2018 07:36:52 PM UTC, comment #123: 

Thanks! The patch works for me (besides a small reject issue). Is there any good reason why one should not apply it to default?

However I do not understand why Rik is not seeing the same dialog. COuld it be qt version related?


Sebastian <sschoeps>
Sun 11 Nov 2018 11:02:34 PM UTC, comment #122: 

Sorry, I can't reproduce this.  I've attached a patch which might help though.  You could try it out.  It disables the message windows when --disable-doc has been used during configure.  There are probably better solutions to this issue.

(file #45407)

Rik <rik5>
Project Administrator
Sun 11 Nov 2018 01:43:03 PM UTC, comment #121: 

@Rik: did your clean your directory? I guess if the configure finds an old qhc file it might install it anyway. I start from a clean directory and I get two error messages whenever I start octave (see attached). Here is my configure line:

./configure --prefix=/usr/local/opt/octave --disable-dependency-tracking --disable-silent-rules --enable-link-all-dependencies --enable-shared --disable-static --without-fltk --with-hdf5-includedir=/usr/local/opt/hdf5/include --with-hdf5-libdir=/usr/local/opt/hdf5/lib --with-x=no --with-blas=-L/usr/local/opt/veclibfort/lib -lvecLibFort --with-portaudio --with-sndfile --with-qt=5 --disable-docs


Sebastian <sschoeps>
Sun 11 Nov 2018 02:38:20 AM UTC, comment #120: 

@Sebastian.  I just built a development tip and configured with '--disable-docs'.  When I run with run-octave I don't see any weird message such as "Could not copy help collection to temporary file. Search capabilities may be affected. Cannot open collection file: /usr/share/octave/5.0.0/doc/octave_interpreter.qhc".  Is this still a problem?  How do I reproduce what you are seeing?

Rik <rik5>
Project Administrator
Thu 13 Sep 2018 06:53:23 AM UTC, comment #119: 

Ok, my previous suggestion did not work. New idea: did you guys consider to make the two error messages

"Could not copy help collection to temporary file. Search capabilities may be affected. Cannot open collection file: /usr/share/octave/5.0.0/doc/octave_interpreter.qhc"


"Could not setup the data required for the documentation viewer. Only help texts in
the Command Window will be available."

that I have to acknowledge at every startup less annoying, e.g. just showing a warning message in terminal? (I compiled head without-docs which is nothing evil...)

Sebastian <sschoeps>
Sat 28 Apr 2018 12:26:02 PM UTC, comment #118: 

Update of comment 115: jwe has fixed the problem for release versions (http://octave.1599824.n4.nabble.com/Remaining-must-fix-bugs-for-4-4-tp4687624p4687733.html) but for development builds it would be still handy if you guys could check at startup whether there is a documentation (*.qhc) and disable the doc browser if not to avoid the strange errors at startup.


Sebastian <sschoeps>
Wed 11 Apr 2018 07:44:21 PM UTC, comment #117: 

I alluded to the highlighting at the end of this post:


On my system, the highlight goes to the right edge, which also doesn't look that good.  If there were to be highlighting, I'd say the best look is an in-paragraph box sort of thing.  But if there is already indentation and different font, maybe the highlighting is a gilded lily.  Perhaps just drop highlighting examples for the 4.4 release and add it back in if people think it is necessary.

Dan Sebald <sebald>
Wed 11 Apr 2018 07:26:08 PM UTC, comment #116: 

I notice that the display of fixed width @example blocks can have a ragged right edge depending on the size of the documentation window.  This isn't critical, but it is still not desirable.  See the attached screenshot.

Rik <rik5>
Project Administrator
Mon 09 Apr 2018 12:23:38 PM UTC, comment #115: 

@Torsten, Dan: There was recently a discussion on the help list (http://octave.1599824.n4.nabble.com/Could-not-copy-help-collection-to-temporary-file-tp4687432.html) about disabling the construction of the documentation widget when "ENABLE_DOCS" is undefined, as we do for the text editor. Is it something easy to do?

Pantxo Diribarne <pantxo>
Project Member
Sat 07 Apr 2018 10:38:31 PM UTC, comment #114: 

I just pushed the more full-feature Ctrl+F interface for search here http://hg.savannah.gnu.org/hgweb/octave/rev/17387d4edd1d.

Rik <rik5>
Project Administrator
Thu 05 Apr 2018 08:32:40 PM UTC, comment #113: 

User's have to buy the full version for configurable bindings.

Dan Sebald <sebald>
Thu 05 Apr 2018 08:20:32 PM UTC, comment #112: 

Should't the shortcuts used for the search be configurable?
However, looking at the deadline for the translation files, which then would have to be updated another time, this is quite hard to get done.

Torsten Lilge <ttl>
Project Member
Thu 05 Apr 2018 04:52:03 PM UTC, comment #111: 

Oh, another thing I was wondering about:

"Ctrl+F: Open and focus search text field, select all text if previous search term exists so typing will immediately overwrite. Repeated hits of Ctrl+F are idempotent, focus remains on search text field, search term selected."

What about the situation in which the user highlights some text in the QTextEdit's content window and then type Ctrl+F?  Should the selected text appear in the "Find:" QLineEdit?  Right now, Ctrl+F just highlights whatever is currently in the QLineEdit box.

Dan Sebald <sebald>
Thu 05 Apr 2018 04:46:04 PM UTC, comment #110: 

@Mike: Oh, like the pre-defined key sequences in this Qt table:



Might as well change this while it's fresh in my mind (don't think I'll look at this anymore)...  Give the attached changeset a try.  I added the search-while-type feature easy enough.  Along with that I also made it "rewind" as the person deletes characters.  That is, until someone types Enter, Ctrl+G, Ctrl+Shift+G or clicks the mouse somewhere, the search anchor point remains the same.

The one thing I would consider changing is that I often don't like in these in-page-find implementations the fact that I just intend to activate the content window and click in the middle of the page, and that's where the search starts from.  That often leaves a half page of content to the top that doesn't get searched, if you follow me.  What we could do is get the cursor position of the upper-left corner of the viewport and start from there (or the lower-right corner if searching backward).

(file #43812)

Dan Sebald <sebald>
Wed 04 Apr 2018 11:54:15 PM UTC, comment #109: 

This is a pretty good start, to say that there is at least a way to do an in-page search in the help viewer.

FWIW, here is how I would expect the search feature to work:

  • Ctrl+F: Open and focus search text field, select all text if previous search term exists so typing will immediately overwrite. Repeated hits of Ctrl+F are idempotent, focus remains on search text field, search term selected.
  • Ctrl+G: Find next match. Works whether or not keyboard focus is on the search text field. Does not move focus to the search text field.
  • Ctrl+Shift+G: Find prevous match. Same as above wrt focus.
  • Enter: Find next match, only if the keyboard focus is on the search text field.
  • Escape: Close the search bar if the keyboard focus is on the search text field.

This is basically how search works in Firefox and in gedit.

I think that F3 and Shift+F3 are also typical aliases for Ctrl+G and Ctrl+Shift+G.

And a future improvement would be to have an incremental search, find and highlight the first matching term as the user types in the search text field without having to press Enter.

Mike Miller <mtmiller>
Project Administrator
Wed 04 Apr 2018 11:22:19 PM UTC, comment #108: 

OK.  I've downloaded the latest stable branch to get up-to-date.  Testing the search feature a bit, I'm going to guess that folks don't want the Ctrl+F to toggle, but want Ctrl+F to jump back to the search window, i.e., Ctrl+F always means go to the search window.  Either Torsten or I can make that change easy enough.  As an example, check out the TortoiseHG (thg) search footer.  It has a "close" button.  In fact, all those features can be implemented, and the find() routine returns a boolean so that one can put up a dialog box "nothing found" easy enough as well.

Dan Sebald <sebald>
Wed 04 Apr 2018 06:07:00 PM UTC, comment #107: 

@Dan: I pushed the no-frills search here (http://hg.savannah.gnu.org/hgweb/octave/rev/9578133ca03e).

Rik <rik5>
Project Administrator
Wed 04 Apr 2018 04:46:15 AM UTC, comment #106: 

Re: comment #104

1) The search results currently displayed in the search pane are directly generated by the Qt help engine. As far as I understand there is no (easy) way to modify this, but I will have a look into it.

Torsten Lilge <ttl>
Project Member
Wed 04 Apr 2018 01:26:16 AM UTC, comment #105: 

Here's a no-frills in-page search.  Forward and backward buttons, return key is same as forward.

(file #43792)

Dan Sebald <sebald>
Tue 03 Apr 2018 09:26:25 PM UTC, comment #104: 

@Pantxo: I pushed your patch for monospace fonts here (http://hg.savannah.gnu.org/hgweb/octave/rev/dd480b75e6e8).  I added a Makefile dependency for OCTAVE_QTHELP_FILES on the HTML css file.  The .qch file wasn't getting re-built at first and I wasn't seeing any change.

Remaining issues:

1) Can the return search result be a direct link to the anchor in the documentation, rather than to the enclosing anchor (such as a chapter)

2) Can Ctrl+F find be implementd to search for text within a page of the documentation?

Rik <rik5>
Project Administrator
Tue 03 Apr 2018 09:08:08 PM UTC, comment #103: 

Since this feature is ongoing, I'll write new bugs here...

With the latest code, dock the Documentation window, click in some other docked widget and the title bar highlight comes to that widget.  Next, click on the title bar widget of the Documentation widget and the highlight does not change from the previous widget to the Documentation widget.  If I click inside the Documentation content, then the focus comes to the widget.

Dan Sebald <sebald>
Tue 03 Apr 2018 07:58:38 PM UTC, comment #102: 

I have pushed csets
providing qt functions for getting the tmp dir and for avoiding the crash after the help data failed to be set up

Torsten Lilge <ttl>
Project Member
Tue 03 Apr 2018 10:29:01 AM UTC, comment #101: 

@Rik (comment #89, issue #1): I attached a patch which adds fallback monospace fonts in octave.css. Currently, the problem is that if Fantasque Mono is not installed on the computer, Qt falls back to a non monospace font. We must thus provide a proper fallback fonts.
A single generic "monospace" does not seam to do the job for me so I also added "Courier New" (present on most Win machines according to https://www.cssfontstack.com/) and "Cousine" which is the default for the terminal on my linux computer (and also the best match for "Courier New" according to fontconfig).

(file #43779)

Pantxo Diribarne <pantxo>
Project Member
Tue 03 Apr 2018 05:23:49 AM UTC, comment #100: 

I've been testing GUI docked-widget relocation in KDE.  One thing I notice is that if one drops a window, not as a tab, but somewhere that makes it stand on its own, often the GUI can grow in size bigger than the screen.  I suppose one just lives with that, at least in the short term.  However, when the GUI gets in this state it tends to become slower at repositioning.  (It seems to me that KDE is more active in terms of refocus and redraw.)  If the Documentation window is visible during the resize and relocation, the GUI motion becomes kind of chunky, probably because there looks to be a great deal of content on the main Documenation screen--a long Table of Contents followed by a detailed node listing.  My guess is that the latter is a bigger contributor to layout speed because there is a node in the left column and short description in the right column.  In summary, is there too much content on the main Documentation page?

Dan Sebald <sebald>
Mon 02 Apr 2018 03:50:19 AM UTC, comment #99: 

Agree with Dan that we should use the cross-platform Qt capabilities to find a temporary directory rather than relying on the TMPDIR environment variable.

Rik <rik5>
Project Administrator
Sat 31 Mar 2018 06:09:42 PM UTC, comment #98: 

OK.  For the temp directory, yes, use the Qt features inside the GUI (I think there is a method for generating temp directories too).

Also, FYI QTextBrowser inherits QTextEdit, which has a find() function:


which will search for and highlight the occurrence of the supplied string.  So all that is needed is to layout some text boxes and buttons in a footer, initially hidden, toggle the hidden state with Cntrl-F, and make some connections.  Unfortunately, the find() above is not a slot, but one can create a slot documentation_browser::do_find() and connect it to one or more of the buttons in the footer, then there should be no need for any new classes.

Dan Sebald <sebald>
Sat 31 Mar 2018 05:23:19 PM UTC, comment #97: 

For fixing the crash when no qhc was found or when the data setup failed, I am going to test whether we just can return from the constructor of the documentation class.

Torsten Lilge <ttl>
Project Member
Sat 31 Mar 2018 05:20:30 PM UTC, comment #96: 

@Pantxo: on my system, TMPDIR is not set, which leads to a non-working documentation (and a crash for a moment). Maybe we should use QString QDir::tempPath() (http://doc.qt.io/qt-5/qdir.html#tempPath).

Torsten Lilge <ttl>
Project Member
Fri 30 Mar 2018 11:14:49 PM UTC, comment #95: 

If so, moving the dialog boxes to the point where the Documentation window is activate (no QCH file) and when the Search button is pressed (no QHC file) should be a fix.

Dan Sebald <sebald>
Fri 30 Mar 2018 10:57:23 PM UTC, comment #94: 

I wonder if that is the same old bug where calling error() on the GUI side leads to a segfault because the error handler is installed only on the Octave main thread.

Rik <rik5>
Project Administrator
Fri 30 Mar 2018 10:46:27 PM UTC, comment #93: 

OK, I pulled and tested that changeset, thanks.

The Documentation search now works from the build directory.

The crash bug is still present, which is in the program code.  I deleted the


files to test what happens:

[Dialog box]
"Could not copy help collection to temporary
file. Search capabilities may be affected."
[select OK button]
[Dialog box]
"Could not setup the data required for the
documentation viewer. Only help texts in
the Console Widget will be available."
[select OK button]
"sebald@linux ~/octave/bug/53006 $ octave exited with signal 11"

Dan Sebald <sebald>
Fri 30 Mar 2018 10:11:54 PM UTC, comment #92: 

@Dan: That was the reason for Pantxo's reverting some unintended changes (see comment #90).

Update to

changeset:   25065:74ece2b45b4f
branch:      stable
user:        Pantxo Diribarne <pantxo.diribarne@gmail.com>
date:        Fri Mar 30 23:00:38 2018 +0200
summary:     Revert unintended changes in cset 1cd3aeda7598

And you can use run-octave --gui to see the help files without having installed Octave previously.

Rik <rik5>
Project Administrator
Fri 30 Mar 2018 09:37:18 PM UTC, comment #91: 

I've tested what I think is the latest code on stable branch.  I can now search from an installed version.  However, there is a problem in the sense that the location of the QHC file is hard-coded into the development environment.  If Octave is not installed, then when I attempt to run from the build tree I get

"Could not copy help collection to temporary
file. Search capabilities may be affected.
Cannot open collection file: /usr/local/share/octave/4.3.0+/doc/octave_interpreter.qhc"

The ramification is that Octave is always looking to the installed location for the file, and if there happened to be a version there while I was doing development on QHC/QCH contents my modifications wouldn't be reflected in my test from the build environment, i.e., "run-octave --gui" without having done a "make install" first.

Dan Sebald <sebald>
Fri 30 Mar 2018 09:29:33 PM UTC, comment #90: 

I reverted some unintended changes here:


Issue #1: Can the CSS file be somewhat adapted for offline rendering? I see that we use webfonts by default. Can this have an impact in some way?

Pantxo Diribarne <pantxo>
Project Member
Fri 30 Mar 2018 06:49:03 PM UTC, comment #89: 

Both patches are now on stable.

I see two issues that should still be addressed.

Issue #1 : Variable width font in @example blocks

The HTML documentation uses a fixed width font for @example blocks which is correct.  It affects the display of mathematical formulas, for example.  To see the effect, try 'doc cosint'.  The integral which defines cosint is not displayed correctly.

Issue #2 : Search returns links to enclosing section, not to the actual location of result in file.

As an example, search for "cosint".  The first returned hit is "GNU Octave: Special Functions".  If I click on the link I get taken to the chapter on special functions, but the entry for cosint requires quite a bit of scrolling.  On the other hand, if I use the Index and click on "cosint" then I am taken directly to the cosint documentation.

Rik <rik5>
Project Administrator
Fri 30 Mar 2018 06:14:45 PM UTC, comment #88: 

I applied both Pantxo's and Torsten's patches and re-built using MXE Octave.  The help browser works for me on Windows XP in a virtual machine.

I will commit both of them shortly.

Rik <rik5>
Project Administrator
Fri 30 Mar 2018 06:05:33 PM UTC, comment #87: 

@Torsten (Re: comment #84): I applied your patch and after a bootstrap-configure-make cycle on a system with Qt 5.9.4, the search in the search tab of the documentation widget still works.

@Pantxo (Re: comment #85): The GUI on Windows (without your patch) does currently not open (b9f0f1aaae3b+ with unrelated changes in ov-java.cc). A message window with "Could not setup the data required for the documentation viewer. [...]" appears. After pressing the "OK" button, Octave crashes.
I did not read all 86 comments so far. Do you think your patch will fix this crash? Otherwise, I can't see how to test the patch on Windows.

Markus Mützel <mmuetzel>
Project Member
Fri 30 Mar 2018 02:17:25 PM UTC, comment #86: 

@Torsten: I forgot

  • The following note from the QHelpEngineCore class doc is another good reason to test on Windows soon:

>> Note: qsqlite4.dll needs to be deployed with the application as the help system uses the sqlite driver when loading help collections

  • In order to test the (un)resistration of compressed help files, you can use Octave's api. For this you need to generate doxygen doc ("make doxyqt"), and then

fname = "/path_to_buid_tree/doc/doxyhtml/doxyqt/octave-cpp-api.qch";
__octave_link_register_doc__ (fname); ## the api is now in the content widget
doc ("QtHandle::Figure") ## Works for me
__octave_link_unregister_doc__ (fname); ## api removed from the content widget

Pantxo Diribarne <pantxo>
Project Member
Fri 30 Mar 2018 01:20:22 PM UTC, comment #85: 

I attached an updated patch that takes care of removing the temporary hidden directory as well. This works on linux but should be tested on other platforms.

(file #43725)

Pantxo Diribarne <pantxo>
Project Member
Fri 30 Mar 2018 12:51:44 PM UTC, comment #84: 

@Pantxo: Thanks for the patch, I am going to test it over the weekend.

Attached a patch that should address the issue with changed members of QHelpSearchQueryWidget in Qt 5.9. It would be nice if someone with Qt 5.9 or higher could test if the global search in the doc widget works.

(file #43724)

Torsten Lilge <ttl>
Project Member
Fri 30 Mar 2018 11:04:53 AM UTC, comment #83: 

@Dan, Torsten, Mike: The patch I provided should be enough to avoid permission issues: both the copy of the collection file and the temporary directory mentioned by Dan are now living in the TMPDIR. I took care of removing the copied collection file, but the temporary directory remains.
On my system, if the copy of the collection is called "/tmp/oct-qhelp-345689", the temporary directory is then automatically named "/tmp/.oct-qhelp-345689/". So, on linux, I could guess the name of the directory and delete it at the same time as the collection, but I don't know if this "." addition is cross platform.

Pantxo Diribarne <pantxo>
Project Member
Thu 29 Mar 2018 09:17:03 PM UTC, comment #82: 

I attached an updated patch in which I implemented the copy approach. The temporary file is deleted after the QHelpEngine.

(file #43718)

Pantxo Diribarne <pantxo>
Project Member
Thu 29 Mar 2018 07:59:46 PM UTC, comment #81: 

Re comment #57: I have updated the translation file with cset

Torsten Lilge <ttl>
Project Member
Thu 29 Mar 2018 07:40:06 PM UTC, comment #80: 

@Mike: I think I happened on some clues as to how Qt Assistant is dealing with this.  It sounds like the QHC file itself holds some information and that upon launching assistant it might do something to make customized copies.  There is a discussion of the app and qhc locations topic here:


and there is mention of using the Qt directory QDesktopServices::DataLocation which is in the following list:


Just guessing, but it may be that the QHC file needs some more work (see example in first link above), or perhaps the DataLocation directory needs defining.

Dan Sebald <sebald>
Thu 29 Mar 2018 05:51:03 PM UTC, comment #79: 

I can confirm that the .octave_interpreter/fts file is needed for full text search to work correctly. I can also confirm that if the doc directory is not writable by me, Octave works fine, but full text searching is non-functional, all search results return failure.

Looking at the Qt code base I don't see an easy way to change this at the moment, it looks hardcoded into the internals of QHelpSearchEngine (the QHelpSearchIndexReader and QHelpSearchIndexWriter internal classes).

Looking at the Qt Assistant program itself, it might be that they have written a separate implementation of QHelpSearchEngine for Qt Assistant that doesn't use a search index database stored on disk.

Mike Miller <mtmiller>
Project Administrator
Thu 29 Mar 2018 05:32:51 PM UTC, comment #78: 

@Torsten: That's a creative idea about moving the QHC and QCH files, but I suspect there'd be a lot of admins upset with that approach.  It potentially leaves big files about in hidden files.

I've been trying to figure out the logic QHelpEngine is using for this and I can't get it.  I've see temp directories in both the launch location and the home of the QHC file.  I've also explored what Qt "assistant" is doing.  I can't see any temporary files or directories anywhere when running assistant--not the launch directory, not any /tmp directories, not where the .qhc file lives.  I'd say go ahead with registration of QHC files rather than constructing the QHelpEngine with the collection file and see what happens; perhaps that doesn't use temporary directories.  After all, Qt assistant is probably using Qt's registration functions because it uses "-collectionFile file" at the command line.

Dan Sebald <sebald>
Thu 29 Mar 2018 04:18:14 PM UTC, comment #77: 

@Pantxo: A patch would be helpful here, thanks.

@Dan: To summarize, it is not required to (re)index the documentation. I remember in my tests, that only after adding this connect (), the search afterwards was working, but since the connect contained a typo, there must have been another effect.

It is not clear to me, how to avoid the problem with the temp. file. Should we copy the compressed help file into a tmp location for working on that copy?

Torsten Lilge <ttl>
Project Member
Thu 29 Mar 2018 04:06:48 PM UTC, comment #76: 

@Dan: I build in the source tree which probably explains why the search feature "just worked" for me.

@Pantxo: The ability to register Octave Forge documentation is going to come in the future, so I don't have any issue with implementing it now if it would also solve a current bug.  Octave does lots of initialization at start-up so adding one more item does not seem like a big deal to me.

Rik <rik5>
Project Administrator
Thu 29 Mar 2018 12:10:46 PM UTC, comment #75: 

I attached a patch for the current stable tip which adds the possibility to register a compressed help file from the interpreter (useful if octave-forge packages provide qch files) and it also fixes the issue of finding octave_interpreter.qhc in the install dir.

With this in place, you can do

__octave_link_register_doc__ ("/path/to/compressedhelp.qch");
__octave_link_unregister_doc__ ("/path/to/compressedhelp.qch");

The problem is that if a compressed help is not unregistered when quitting Octave then the base collection is left modified and will contain non default data. To solve this we should not initialize the QHelpEngine with an existing collection but use an empty one and register octave_interpreter.qch by default. If you agree with this, I can provide a patch (this will eliminate the need for octave_interpreter.qhc and only qhelpgenerator will be used).

(file #43715)

Pantxo Diribarne <pantxo>
Project Member
Thu 29 Mar 2018 09:26:48 AM UTC, comment #74: 

OK, I've found the issue.  The QHelpEngine or one of its associated components is generating a hidden temporary directory.  With the hard-coded address and copies in the launch directory, after launching Octave GUI there appears

sebald@linux ~/octave/bug/53006 $ ls -la
drwxrwxr-x  2 sebald sebald    4096 .octave_interpreter

sebald@linux ~/octave/bug/53006 $ ls -la .octave_interpreter/
total 1808
drwxrwxr-x 2 sebald sebald    4096 .
drwxrwxr-x 3 sebald sebald    4096 ..
-rw-rw-r-- 1 sebald sebald 1833841 _218.cfs
-rw-rw-r-- 1 sebald sebald       4 deletable
-rw-rw-r-- 1 sebald sebald      29 segments

After exiting the program and taking out the hard-coded path and recompiling, I removed the above hidden directory and re-ran Octave GUI.  No new hidden directory appeared.

So, my guess is that the hidden directory is being attempted in the non-permission build directory.  Whether this is a consequence of attempting to use the [build-dir]/run-octave environment setup or something more general, it can't be that an installed Octave attempts to create a hidden directory in the location of the QHC file.  To investigate, I've installed Octave, run the GUI and get a model error dialog:

"Could not setup the data required for the documentation viewer. Only help texts in the Console Widget will be available."

and after clicking "OK" Octave crashes.  Launch again, "OK", crash.

The usual issues.  I realize this is in the nascent stage, but it takes time to make new features work robustly.

Dan Sebald <sebald>
Thu 29 Mar 2018 08:32:20 AM UTC, comment #73: 

What I've done is copy

-rw-r--r-- 1 sebald sebald 4994048 octave_interpreter.qch
-rw-r--r-- 1 sebald sebald    8192 octave_interpreter.qhc

to the directory I launch from and then temporarily hard code that launch directory in place of "collection" QString.  The search works then.

One thing I noticed is that the octave_interpreter.qhc file was being updated by the GUI upon initializing the QHelpEngine.  I removed

//    connect(m_help_engine, SIGNAL(setupFinished()),
//            m_help_engine->searchEngine(), SLOT(reindexDocumentation()));

and the time-stamp no longer change on the octave_interpreter.qhc file.  Unfortunately, that wasn't enough to make the search work for the collection file in a separate account.  Can you think of any other steps in the QHelpEngine initialization process that would require one of those files to need write permission?

Dan Sebald <sebald>
Thu 29 Mar 2018 07:53:00 AM UTC, comment #72: 

I looked at all the data sent into that ->search() call.  Everything looked good... except the following may be a typo:

     connect(m_help_engine, SIGNAL(setupFinished()),
-            m_help_engine->searchEngine(), SLOT(indexDocumentation()));
+            m_help_engine->searchEngine(), SLOT(reindexDocumentation()));

     if (! m_help_engine->setupData())

but it doesn't matter as far as what I'm looking at because re-indexing probably isn't necessary in this limited use.  The search engine simply doesn't execute.

It then dawned on me what the issue is.  I put the build tree in a separate account to keep from archiving/backup all those object files.  So, the directory/account I'm running from doesn't have the permission for the build tree.  I then ran the GUI from that account, and the search then works.

Something to think about I guess.  Once this is installed, the executable and QHC file will be in a directory not owned by the user running the GUI.  Is there some type of temporary directory location that needs to defined, maybe where the QHelpSearchEngine can place a hash or intermediate results file?

Dan Sebald <sebald>
Thu 29 Mar 2018 05:59:19 AM UTC, comment #71: 

No, I don't have Qt 5.9 (5.5.1 on this machine).  I'm surprised Qt would make such a drastic change.  I just looked at the header file


and see

qhelpsearchengine.h:    void search(const QList<QHelpSearchQuery> &queryList);

so it must be something else.  I'll look around.

I just noticed this superfluous check on m_help_engine:

    if (! m_help_engine->setupData())
        QMessageBox::warning (this, tr ("Octave Documentation"),
                              tr ("Could not setup the data required for the\n"
                                  "documentation viewer. Only help texts in\n"
                                  "the Console Widget will be available."));
        if (m_help_engine)
            delete m_help_engine;
            m_help_engine = 0;

m_help_engine was used to find m_help_engine->setupData(), so it must be valid by the time of the second test.

Regarding Rik's observation about search results, the results are the same as what "assistant -collectionFile octave_interpreter.qhc" generates.  I don't know who's controlling that info (Qt search engine innards, or something else), but a more useful display of info would be maybe five words on either side of the found word, with the found word in bold...but don't spend too much effort on that.  What is important though is the search results are missing the main entries that one would like to be at the top of the list, i.e., jump to first, and I don't understand why.  In your example there are two items listed, but I'm attaching a plot showing the occurrence of "acoth" that is not found and that is the one we want to jump to first, I believe.  This isn't something that Torsten's changeset addresses, but probably something to do with the way information is formatted in the QHC file, e.g., section-markers or highlight-markers around the word "acoth" or maybe a format that breaks the word "acoth" up internally (something that HTML often does).

Thoughts on the cream colored highlighting of code lines with the grey background?  Is it possible to make the code inside an in-paragraph box rather than have the cream lines extend all the way to the right border?  The long line has a sort of disruptive flow as though it is a new section or header.

Dan Sebald <sebald>
Thu 29 Mar 2018 05:12:10 AM UTC, comment #70: 

@Rik: I have not yet pushed the patch into the repo because I was waiting for a decision whether to include it into 4.4 or not (comment #53).

@Dan: Yes, you are right; I guess you have Qt 5.9 or higher? The query () method is marked as obsolete, however it should still work. The search () method obviously has changed with 5.9, now expecting a QString instead of QList<QHelpSearchQuery>.

Torsten Lilge <ttl>
Project Member
Thu 29 Mar 2018 01:58:29 AM UTC, comment #69: 

@Torsten: I've tried what I think is the latest code in the repository (default, merged from the stable branch), but get no response to pressing the Search button of the query signal.

I do see this occur:

  void documentation::global_search (void)
std::cerr << "GL SEARCH\n";
    QList<QHelpSearchQuery> queries
      = m_help_engine->searchEngine ()->queryWidget ()->query ();
    m_help_engine->searchEngine ()->search (queries);

However, I don't understand the above use of QHelpSearchQuery passed via the search () signal.  The searchEngine() is of type QHelpSearchEngine *.  But the search() shown here:


passes a QString, not a QList<QHelpSearchQuery> and QHelpSearchQuery


Doesn't seem to inherit a QString.

I haven't looked much beyond that.

Dan Sebald <sebald>
Wed 28 Mar 2018 09:12:08 PM UTC, comment #68: 

The presentation of the search results might be the next thing to improve.  I did a search for acotd and I got the following:

GNU Octave: Trigonometry
GNU Octave: Function Index

The first item in each hit is useful--telling me which section of the documentation the link is in--but the next bit telling me the file is less so.  Given the way we have things set up, everything will have the very long prefix "qthelp://org.octave.interpreter-1.0/doc/octave.html/".

Rik <rik5>
Project Administrator
Wed 28 Mar 2018 09:09:02 PM UTC, comment #67: 

@Torsten: This is coming along quite nicely.  I think it is well enough along that development can now take place in the Mercurial repository, rather than in patches to this bug report.  I applied your patch, along with cleaning up some indentations, here http://hg.savannah.gnu.org/hgweb/octave/rev/ba5af45bbfc4.

Rik <rik5>
Project Administrator
Wed 28 Mar 2018 08:24:33 PM UTC, comment #66: 

Agreed, global search is what I was referring to, not in-page search.  But if you are on a roll, it wouldn't surprise me if Qt has a pre-built "cntrl-f" like object as part of some HTML viewer or some other window (i.e., embed your result in some special window), but I haven't looked.

Dan Sebald <sebald>
Wed 28 Mar 2018 07:52:26 PM UTC, comment #65: 

Next version of the patch with the new doc browser, including global search and index search. Not yet included is searching the displayed help page, which is possibly less important than the other search functionalities.

(file #43713)

Torsten Lilge <ttl>
Project Member
Wed 28 Mar 2018 05:59:09 PM UTC, comment #64: 

Can we please keep the bug log on topic? If you want to discuss the release please use the maintainers mailing list, this is not the place.

Re-summarizing from comment #58, the Qt help files are now built and ready to be used. We have a patch to provide the help widget and to tie it into the 'doc' command, but no search capability yet.

Mike Miller <mtmiller>
Project Administrator
Wed 28 Mar 2018 05:47:53 PM UTC, comment #63: 

The reason some of these releases have taken so long is because the underlying addition to the software is not well designed.  Parts are tossed in with the expectation that someone will fix the loose threads somehow magically down the line without coming up with some proper design strategy.  In particular, the game changed with the addition of the GUI and its inherent cross-thread issues.

But tossing in rushed and poorly thought out software tends to mean issues will linger because they become insurmountable for one mortal to tackle.  Instead, folks try to make quick fixes around the poor designs and put off the root cause thereby making the issues further entrenched.  One can sense if a bug is merely a case of having a little extra time to address or if it is quicksand.

The Mathworks is a moderately sized team of paid employees with trained backgrounds in computer science using nice development tools.  This project is mainly user based and no comparison.  Also, the most prolific programmer is no longer at free disposal to the project.

I didn't see many people spending their end-of-the-year holiday on putting together a 4.2.2 software release, and I was paying attention because that was what I was expecting.  A lot of countries have a cultural tradition of spending their holidays on extended trips, home renovations and bigger personal projects.

I think the better approach is what you started out doing: identify any showstopper bugs.  First comes the builder market.  If the external builders have problems with consistent building, then it is a problem out of the gate.  Second would be to focus on the most used elements and what would generate the most Savannah bug reports.  (That's my view point: make something work and finish it while its fresh in one's mind, be done with it without having to revisit it in bug report after bug report.)  But if the project can't even identify what the issues are after what looks like a fair amount of new features and retooling, don't release it.

As for releasing something near the start of summer, it seems to me that the most user activity is post-summer, e.g., "my prof said I have to use this software and it doesn't work", workers coming off vacation, etc.  Maybe it is better to use the summer period as beta testing a release candidate with all the summer-of-coding-love activity on branches.  More frequent bug-fix releases are fine, so long as they aren't bug-make releases.

I trust the changeset here would be robust because it's primarily within the realm of Qt-developed objects, but not having a search engine means user's clamoring for one.  The fewer requests, the better.

Dan Sebald <sebald>
Wed 28 Mar 2018 03:50:44 PM UTC, comment #62: 

One of the discussions we had at OctConf 2018 was when and how often to make releases.  Previously, Octave has done releases based on features, i.e., when we felt enough new code had accumulated we pushed out a release.  This was not ideal for the downstream users and distribution maintainers.  An important bug, such as one resolving a segfault, might be languishing for more than a year while we waited for enough code to gather to make a release.  And it definitely puts Octave out of step with the rest of the SW world which has been moving to time-based releases.  Matlab, as the most relevant example, always releases twice a year.  You can plan on it, and even if no new features are present there are at least bug fix opportunities every 6 months.

Based on all of that reasoning, we decided to move to a time-based release with code freeze Dec. 15th and the release around Jan. 15th of the next year.  Many of the Octave volunteers have some time off around the holidays which we hope can be dedicated to helping get the Octave release out the door.

Another final argument for the more frequent release schedule has been the fact that because we do it so infrequently, the release process itself is quite a chore.  If we are releasing more frequently then we not only get better at it, but we don't feel so bad about simply leaving in some bugs that we don't have time to fix right now, but will be addressed by the next release.

With all of this in mind, I think we do need to get this next version of Octave released.  The Variable Editor does have a lot of issues, but we could always put a note in the NEWS that this is still experimental.  It didn't exist in the GUI before, and Octave is highly functional without it.  If someone never uses that feature in 4.4 they will still have benefited by having access to all of the other improvements to the core of Octave that have occurred over what is now close to two years.

Rik <rik5>
Project Administrator
Wed 28 Mar 2018 07:06:06 AM UTC, comment #61: 

Release buggy software and expect more bug reports, in triplicate.  Someone has to address all of those, and frankly there aren't the resources to do so, evidenced by the new entries in Savannah in the past few weeks and half of that long list is still pink.  I could add a few more bugs to the list concerning the way Variable Editor does select-cut-and-paste, but why overload the whole thing when there are so many others to address?

There has now been in the past months changes to finally address that NVidia driver build problem and changes that add another QtHelp package requirement (for the GUI, and for constructing the .qhc file).  Based on bug reports like this


I suspect there are going to be a lot of systems running into build errors and the user not knowing how to proceed forward.

Here's the bug fix list


which isn't even so far as to identify the bugs that need fixing, so how can one conclude there is even some goal to meet? 

Here's the discussion thread on 4.4 release:


in which Rik states he doesn't think 4.4. could be done at the end of March, but yes 4.2.2 should be ready at the end of the year...which ended up being Mar 13, 2018.

Dan Sebald <sebald>
Wed 28 Mar 2018 06:00:53 AM UTC, comment #60: 

2 weeks seems realistic and should be met.

Michael Godfrey <godfrey>
Project Member
Wed 28 Mar 2018 05:19:59 AM UTC, comment #59: 

Two weeks, Rik?  More realistic would be a candidate in two or three months, after which beta-testers can try for a couple weeks.  The stuff I've been looking at lately (KDE top-level window not appearing, hence unmovable windows) requires testers on multiple systems to find all the various quirks.  Then there are what look to be rather hi-priority general bugs that keep rolling in on Savannah.

As for this particular documentation feature, my feeling is that without a search option it's a no-go because users will be asking for search capability as soon as they see the doc-book, help-book look-and-feel.  That's the way it goes.

Yes, the colon should be filter out of the section titles.

Dan Sebald <sebald>
Wed 28 Mar 2018 04:59:36 AM UTC, comment #58: 

Getting read for this better documentation, I checked in this change (http://hg.savannah.gnu.org/hgweb/octave/rev/336c167b1883) to strip the prepended ':' from @deftypefn entries in the HTML and eventually Qt help.

Rik <rik5>
Project Administrator
Tue 27 Mar 2018 11:13:41 PM UTC, comment #57: 

@Torsten: 4.4 is probably still 2 weeks away.  Is that enough time for you?  Also, can you re-generate the Qt translation files?  I would like to get the translators working on any new strings.  Unless, of course, adding the Search capability is going to add new strings to the GUI in which case it can be done after that.

Rik <rik5>
Project Administrator
Tue 27 Mar 2018 07:23:55 PM UTC, comment #56: 

I was wondering if we could get away from it by supplying our own macro expansion for deftypefn in macros.texi that would override the default.  But, I don't want to work too hard.  The perl thing works today and would be easy to implement.

Rik <rik5>
Project Administrator
Tue 27 Mar 2018 06:42:09 PM UTC, comment #55: 

The colon is always there, it is meant to separate the Category of the function from its type and name. All of the @def macros include a Category argument, which we always leave blank, and the colon is always emitted.

Mike Miller <mtmiller>
Project Administrator
Tue 27 Mar 2018 06:41:16 PM UTC, comment #54: 

When exactly will version 4.4 released. I am currently working on the search functionalities.

Torsten Lilge <ttl>
Project Member
Tue 27 Mar 2018 06:32:01 PM UTC, comment #53: 

@jwe: Should we go ahead and change the browser for 4.4?  It doesn't have search, but is otherwise quite nice.

Also, is there a simple way to change the expansion of @deftypefn to remove the ': ' which is generated at the start of each usage?  Otherwise, this Perl one-liner does the trick

perl -i.bak -pe 's|(?<=</a>): ||g' *

I used that in the directory octave.html to modify the HTML files before they are converted to Qt help files.

Rik <rik5>
Project Administrator
Tue 27 Mar 2018 01:58:39 PM UTC, comment #52: 

I tried "doc axes" from the terminal and a beautiful documentation popped up. For free we also have standard default short cuts (I guess we want to control this in the future but that no priority): zooming (CTRL+Mouse Weel), previous/next page (ALT+Left/RightArrow)... I also tried the "show documentation for..." context menu in the editor and it works great.

Many Thanks Torsten, that is great!

Note for those using debian: in order to compile, I needed to install "qttools5-dev" package which was not needed up to now. Without it the configure script would fall back to Qt4 (for which I had the QtHelp module installed).

Pantxo Diribarne <pantxo>
Project Member
Tue 27 Mar 2018 10:52:30 AM UTC, comment #51: 

oops, here the right one.

(file #43697)

Torsten Lilge <ttl>
Project Member
Tue 27 Mar 2018 06:45:11 AM UTC, comment #50: 

@Torsten: I think you attached the wrong patch.

Pantxo Diribarne <pantxo>
Project Member
Tue 27 Mar 2018 05:57:02 AM UTC, comment #49: 

Please find attached a first draft version of the new documentation browser. The patch is not yet fully documented and does not yet provide any search functionality (index search, global search and search within the shown help text). This will be added next.

(file #43693)

Torsten Lilge <ttl>
Project Member
Fri 23 Mar 2018 07:37:26 AM UTC, comment #48: 

Yeah, I don't know.  I mean, I'm wondering what people are envisioning for this that it could be on the order of what Qt Assistant is doing.  I'm looking at the qhc file right now: there are multiple pages/levels, search, contents, index, back, home, print, find.  Are all these features going to be within the Octave GUI somehow the way that there is a Documentation window?

Also, the first thing the user will do after opening the new would-be help feature in the GUI is s/he will float the window, because looking at Qt Assistant the QHC contents obviously requires the associated QTextView to be so wide to avoid cutoff that it can't be contained within the GUI along with any other windows.  If Qt Assistant could be made to hide via the GUI "Window" dropdown menu and had an Octave-custom Icon for the TaskBar, no one would notice its a separate process.

With remote control, if I'm recalling correctly, one might even be able to make "help funcxyz" jump to the proper location in Qt Assistant.

Dan Sebald <sebald>
Thu 22 Mar 2018 10:23:45 PM UTC, comment #47: 

I agree with Mike, if the integration of the html help into the current documentation widget can't be done in time (I was willing to help but have not much time currently) there is not much benefit in using a qprocess to launch assistant: just use the commands provided in comment #28 and search by hand. 

Pantxo Diribarne <pantxo>
Project Member
Thu 22 Mar 2018 05:06:41 PM UTC, comment #46: 

The goal of all of this is to replace the current plain text Documentation browser. If we don't have a way to do that with the Qt help files, then we can leave things as they are and postpone it until we do have time. I don't see any point in adding a launcher for a separate Qt Assistant program.

Mike Miller <mtmiller>
Project Administrator
Thu 22 Mar 2018 04:51:13 PM UTC, comment #45: 

@Torsten Comment #42:  I see the Qt help-engine tools:


They're nice (without the search engine object, it would be a no-go).  However, there's still some work in figuring out what to do with those search-results as far as placing them somewhere within the GUI.

QVector<QHelpSearchResult> searchResults(int start, int end)

Put them in a combo-box?  On their own new octave_dock_widget?  Provide quick links to those items one puts in a combo box so that it jumps to the proper location in the QTextBrowser one creates to display the QHC?  There are some tools there to aid in this, in particular a widget to help prep for the search:

QHelpSearchQueryWidget *queryWidget()

and a widget to display the search results:

QHelpSearchResultWidget *resultWidget()

I suspect they are the exact same widget's that QtAssistant uses.

My thought was that we could just leave the current Help->Documentation as is and add another line

On Disk

for which the Assistant selection just launches QtAssistant, a few hours work.

I'd say evaluate your effort and the benefit the end result provides before diving in too deep.  For me, "help spiffyfunction" along with the "See alsos" has always been pretty good.

Dan Sebald <sebald>
Thu 22 Mar 2018 04:20:54 PM UTC, comment #44: 

Threads and processes are two different things.  Threads share memory and must coordinate using mutex's and the like and should be designed well from the start.  A process is a fairly self-contained entity, as the QtAssistant is.  QtAssistant has its own search engine.  It's a stand-alone thing, much like what Windows uses for documentation...my memory of it anyway; perhaps WIndows has some new kind of help system.  (The point is that QtAssistant might be a format that is quite familiar to Windows users.)  The thing one doesn't get is a shared icon that will group with other icons in the KDE/Plasma manager.  If you are imagining a sophisticated integration of Octave command line searching into the QHC file, QtAssistant won't do that, but as far as ease, can't get much easier than launching a process with the proper launch command.

Dan Sebald <sebald>
Thu 22 Mar 2018 03:15:01 PM UTC, comment #43: 

I'd rather stay within a single process if possible.  Having the Octave thread and the QT GUI thread has been difficult enough.  Opening yet another external process and coordinating that seems difficult.

Rik <rik5>
Project Administrator
Thu 22 Mar 2018 12:14:05 PM UTC, comment #42: 

To my understanding, the use of the QHelpEngine is preferred over the assistant application. This gives us more flexibility and a better embedding into the existing GUI (see comment #17, comment #18, comment #19).

Torsten Lilge <ttl>
Project Member
Thu 22 Mar 2018 07:43:53 AM UTC, comment #41: 

I've done this type of Qt helper doc before.  It boils down to opening a process for the external program and giving it the address of the qhc file.  I think there is a way to have some type of coordination between the two processes as well.  The app is something like "assistant -collectionFile [octave's path/filename.qhc] -remoteControl".  Oh, and when it comes time to shut down the GUI, check if the help-process is still running (i.e., the user didn't close it on his or her own), if so, terminate the process.  I too will be rather busy for the next half-week, but let me know if you need help when you get around to it.

Dan Sebald <sebald>
Thu 22 Mar 2018 06:53:35 AM UTC, comment #40: 

I would like to do this but am currently really short of time and can not estimate how long this might take. I will have a closer look on how this can be implemented tonight or over the weekend.

Torsten Lilge <ttl>
Project Member
Wed 21 Mar 2018 10:57:49 PM UTC, comment #39: 

The necessary Qt Help files are now generated as part of the build process.  Can someone who understands Qt hook these up to the GUI?

Rik <rik5>
Project Administrator
Thu 15 Mar 2018 01:49:44 AM UTC, comment #38: 

I made a few more build system changes related to this.

The stamp file approach was broken for me. For example, if one or both of the qch and qhc files were deleted but the stamp file left, the build rule was not executed again. We normally only use stamp files when the build creates a new directory and copies files into it, the stamp file acts as a proxy for the modification time of the directory. So I took out the stamp file for this build rule here


And then when I tried to do a 'make install' I noticed that the local install rules were not correct, and aren't really necessary. So I cleaned that up with


For now, assuming I have Python 2 with lxml, I can build and install.

Mike Miller <mtmiller>
Project Administrator
Wed 14 Mar 2018 10:00:06 PM UTC, comment #37: 

@Torsten: We have definitely decided to produce the documentation files for 4.4.  It would also be excellent if the Qt GUI side was configured to use them for the 4.4 release.

I believe this is not difficult, but I am not a GUI programmer.

Rik <rik5>
Project Administrator
Wed 14 Mar 2018 09:57:04 PM UTC, comment #36: 

@Mike: I pushed this cset in accordance with your remarks


@Torsten: it depends on someone doing the job :-), but it would be great to have it for 4.4.

Pantxo Diribarne <pantxo>
Project Member
Wed 14 Mar 2018 09:24:47 PM UTC, comment #35: 

Shall the new help system be already included in the upcoming 4.4 release?

Torsten Lilge <ttl>
Project Member
Wed 14 Mar 2018 06:20:08 PM UTC, comment #34: 

@Mike: All true.  I will take a look at this sometime on the 10-hour flight back to the U.S. on Saturday.

Rik <rik5>
Project Administrator
Wed 14 Mar 2018 06:12:48 PM UTC, comment #33: 

And lastly, the .octave-qthelp-stamp file should also be included in doc_EXTRA_DIST so the end-user does not hit the build rule.

Mike Miller <mtmiller>
Project Administrator
Wed 14 Mar 2018 04:43:00 PM UTC, comment #32: 

Also nothing is actually creating the .octave-qthelp-stamp file, there should be a 'touch $@' at the end of the build rule.

Mike Miller <mtmiller>
Project Administrator
Wed 14 Mar 2018 04:37:59 PM UTC, comment #31: 

Ok thanks. I did just try to port it to the built-in xml.etree myself, and I agree, it has some problems with HTML parsing.

I do have some slight tweaks to the Python script to support Python 3, but I can hold off on that to see what you and Rik come up with.

Mike Miller <mtmiller>
Project Administrator
Wed 14 Mar 2018 04:30:40 PM UTC, comment #30: 

Ok sorry, I incorrectly assumed that lxml was part of any installation. The answer is yes lxml supports parsing html files which most xml libraries don't (including the builtin python xml module).
Rik will try and take a look at doing this in bare Perl with regular expressions only (no dependency) or we could end up requiring lxml.

Pantxo Diribarne <pantxo>
Project Member
Wed 14 Mar 2018 04:13:19 PM UTC, comment #29: 

I am not familiar with the Python lxml package. Is there a strong reason to prefer it over the built-in xml package?

I am in favor of easing maintenance burden, if lxml makes it vastly easier to keep this script simple, please do use it. But if the prepare_qhelp.py script can be written to use the built-in xml package, that would ease the build requirements a little bit.

  GEN      doc/interpreter/.octave-qthelp-stamp
Traceback (most recent call last):
  File "../doc/interpreter/prepare_qhelp.py", line 27, in <module>
    import lxml.html as lh
ModuleNotFoundError: No module named 'lxml'
Makefile:27803: recipe for target 'doc/interpreter/.octave-qthelp-stamp' failed

Mike Miller <mtmiller>
Project Administrator
Wed 14 Mar 2018 03:02:38 PM UTC, comment #28: 

Rik, Kai and myself have worked on integrating the generation of Qt help files for the C++ API (http://hg.savannah.gnu.org/hgweb/octave/rev/486bc22482ca) and for the manual (http://hg.savannah.gnu.org/hgweb/octave/rev/7c7b60dd4d4c). The latter is installed along with octave, in /share/octave/VERSION/doc/. You can now run assistant to look at the manual from octave:

## In a run-octave session
collection = getenv ("OCTAVE_QTHELP_COLLECTION")
## In an octave session
## collection = fullfile (__octave_config_info__ ("octdocdir"), "octave_interpreter.qhc");
system (sprintf ("assistant -collectionFile %s", collection))

We won't install the C++ API help files since they are too large, and are not intended for the average user. The idea is that they could be distributed through a dedicated Octave-Forge package in the future, and be registered at run time.

Pantxo Diribarne <pantxo>
Project Member
Wed 14 Feb 2018 11:21:43 AM UTC, comment #27: 

@Rik: Good idea and great to know you will be there!

Pantxo Diribarne <pantxo>
Project Member
Tue 13 Feb 2018 04:30:31 PM UTC, comment #26: 

I'm very busy at work right now.  I propose that we work on finalizing this changeset during one of the code sprints at OctConf 2018.

Rik <rik5>
Project Administrator
Mon 12 Feb 2018 10:57:37 PM UTC, comment #25: 

I attached a patch that simply adds the python script (updated from comment #24) in doc/interpreter and changes Doxyfile.in in order to generate a octave-cpp-api.qch in doc/doxyhtml/. Making seriously the necessary changes in doc/intepreter/module.mk is beyond my skills.

(file #43267)

Pantxo Diribarne <pantxo>
Project Member
Mon 12 Feb 2018 12:19:05 PM UTC, comment #24: 

My first try at having the qt help files generated by octave was unsucessfull ... but I can summarize what I think has to be done:

  • Check the presence of both qhelpgenerator and qcollectiongenerator at configure time, and define $(QCOLLECTIONGENERATOR) and $(QHELPGENERATOR)
  • by default generate both .qch and .qhc for the interpreter, so that the QHelpEngine (the help manager for the doc browser) can be initialized with a default collection that only contains the interpreter documentation. The make rule to produce interpreter_qthelp.qch and interpreter_qthelp.qhc should look like:

        python $(srcdir)/doc/interpreter/prepare_qhelp.py \
         interpreter_qthelp ./octave.html
        $(QCOLLECTIONGENERATOR) interpreter_qthelp.qhcp -o interpreter_qthelp.qhc
        rm -f interpreter_qthelp.qhcp interpreter_qthelp.qhp

  • if doxygen is run, generate the associated .qch file, which can be registered by the QHelpEngine into the default collection at run time. For this the diff in comment #20 must be modified to replace "qhelpgenerator" by $(QHELPGENERATOR), found at configure time.
  • All files, interpreter_qthelp.qch/qhc and eventually cpp-api_qthelp.qch, should be installed in some convenient place where the GUI can access them (share/doc?). There should also be an environment variable set by run-octave (e.g. $OCTAVE_QTHELP_DIR) so that files can be located in the build tree.

I attached the modified python script that should be added in doc/interpreter.

(file #43259)

Pantxo Diribarne <pantxo>
Project Member
Fri 09 Feb 2018 11:24:49 PM UTC, comment #23: 

No worries.  I'll make sure everything builds properly again once we have things checked in.

Rik <rik5>
Project Administrator
Fri 09 Feb 2018 11:09:58 PM UTC, comment #22: 

@Rik: I'd be happy to do a step forward and make the compressed help file(s) available so that the GUI development (@Torsten: are you willing to give it a try?) and then the adaptation of the "doc" function can go on.

I can polish the python script, add a license here and a "No edit" header there, but I don't fill quite confident when it comes to manipulating the build system. I'll definitely need some help :-).

Pantxo Diribarne <pantxo>
Project Member
Fri 09 Feb 2018 06:49:20 PM UTC, comment #21: 

This seems reasonably far along.  I support the approach of using HTML and then a QTextBrowser for control over the final appearance.

@Pantxo: As long as we are reasonably certain that we can add the search features and get back to where we are today in terms of functionality, do you want to check this code in?  I feel that it is somewhat hard to manage development of such a big feature outside of Mercurial.

For the time being, we can just use the Python script since all developers will have that language installed anyways.

Rik <rik5>
Project Administrator
Thu 08 Feb 2018 09:03:10 AM UTC, comment #20: 

I tried to have doxygen generate the compressed help file for the c++ api and it works pretty well. The following change in Doxyfile.in is enough to produce it:

diff -r 7b6a5336ddb3 doc/doxyhtml/Doxyfile.in
--- a/doc/doxyhtml/Doxyfile.in        Tue Jan 09 08:56:31 2018 -0500
+++ b/doc/doxyhtml/Doxyfile.in        Wed Feb 07 23:36:59 2018 +0100
@@ -518,6 +518,52 @@

+# Configuration options related to the Qt Compressed Help output
+# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
+# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that
+# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed
+# Help (.qch) of the generated HTML documentation.
+GENERATE_QHP           = YES
+# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to
+# specify the file name of the resulting .qch file. The path specified is
+# relative to the HTML output folder.
+QCH_FILE               = ./octave-cpp-api.qch
+# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help
+# Project output.
+QHP_NAMESPACE          = "com.octave.cpp-api"
+# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating
+# Qt Help Project output.
+# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom
+# filter to add.
+# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the
+# custom filter to add.
+# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
+# project's filter section matches.
+# Where to find the qhelpgenerator
+QHG_LOCATION       = "qhelpgenerator"
# Configuration options related to the LaTeX output

The only glitch I can see is that octave's logo is not included in the qch file.

Pantxo Diribarne <pantxo>
Project Member
Sun 04 Feb 2018 08:02:27 AM UTC, comment #19: 

@Pantxo: you are right, this is exactly what I meant (I have missed this script). Following this approach, we should have full control on the display of the related html help file.

Torsten Lilge <ttl>
Project Member
Sat 03 Feb 2018 11:50:53 PM UTC, comment #18: 

@Torsten: yes, this is what the example pyqt script in comment #9 does. This probably allows a more fine tuning, e.g. fonts, than the set of commands that you can pipe to a QAssistant process (and without the hassle of having to maintain the process). 

Pantxo Diribarne <pantxo>
Project Member
Sat 03 Feb 2018 11:06:15 AM UTC, comment #17: 

As far as I understand, we are not forced to use the Qt-Assistant application when using the QtHelp framework. The latter provides an API for context sensitive access and searching. Results can then be displayed by the application, e.g., in a QTextBrowser (http://doc.qt.io/qt-5/qthelp-framework.html).

Torsten Lilge <ttl>
Project Member
Fri 02 Feb 2018 07:59:20 PM UTC, comment #16: 

That QtPDF module is pretty cutting edge, so might not be compatible with older Qt versions (not sure how backward compatibility works for the Qt project).  Plus, it is a module, which (I don't know) could be an add-on rather than part of the Qt definition.

Also, it looks like a wrapper of some existing PDF viewer, which would require that particular PDF viewer on one's system.  Individual users might have a preference for what PDF viewer they use, so maybe it would be better to approach that as a system launch that opens the PDF file in the dafault PDF browser.

I think Qt assistant (part of the Qt definition) should at least be an option.  One reason is that Qt assistant is very Windows-ish, Windows having had that help format going back decades.  So Qt assistant might appeal to Windows users.

Dan Sebald <sebald>
Fri 02 Feb 2018 07:28:12 PM UTC, comment #15: 

I think it is correct to have doc go straight to the entry if possible, and to a list of choices if necessary.

How do we handle the issue about fixed width fonts versus variable width fonts?  Do we still use Qt Assistant but just require a fixed width font?  Or do we use a Qt Help Viewer that can just view HTML?

Also, what about QtPDF module?  See http://blog.qt.io/blog/2017/01/30/new-qtpdf-qtlabs-module.  That might be a way to get good looking formulas as well.

Rik <rik5>
Project Administrator
Fri 02 Feb 2018 09:11:50 AM UTC, comment #14: 

I think what we want is to have the "doc" function open the documentation browser, e.g:

  • "doc ('integral')": would open a new tab with the documentation for integral.m shown at the right node
  • "doc ('integrate')": would open a new tab with a list of links to pages where the word 'integrate' appears

This can't be done with assistant I think. Another reason why we probably want to have our own QtHelp widgets is that we could select code in the documentation and run it in terminal (as we are able to do from the editor).

The workflow for responding to "doc (word)" could be :
call "entry = _qt_get_doc_entry_ (word, qhcfile)"

  • if there is a single entry : "__qt_show_doc_entry (word, qhcfile)"
  • if no entry "entries = lookfor (word)".
    • if there is a single element in entries "__qt_show_doc_entry (entries(1), qhcfile)"
    • if there are multiple entries "__qt_show_doc_links (entries, qhcfile)"

Or maybe we can use directly QtHelp search capabilities to replace the "lookfor" step.

Pantxo Diribarne <pantxo>
Project Member
Fri 02 Feb 2018 02:44:27 AM UTC, comment #13: 

Oh, I should add, it wouldn't be difficult to launch Qt assistant from Help::Documentation::Online in the main drop-down menu.  Just need to know the qhc file to point to once it is installed.

Dan Sebald <sebald>
Fri 02 Feb 2018 02:42:40 AM UTC, comment #12: 

I tested the Qt-help-contents.  It looks and behaves like what I expect from the Qt assistant.  Looks nice.

There is a "Search" in the Qt assistant, so I'm not sure what is being referred to that search needs to be added.  What's strange though is that I do a search, say, "log plot" and I get a list of entries beginning with

GNU Octave: Function Index

What is the HTML/URL address for?

Dan Sebald <sebald>
Thu 01 Feb 2018 09:58:34 PM UTC, comment #11: 

Impressively easy to generate reasonable looking documentation.

A couple quick things I noticed: First, it still isn't as good as the PDF typeset documentation.  Formulas use the @ifinfo section of the TeXinfo source which means they are text-based.  This is no worse than what we have today with the current built-in viewer, but still not as nice.

Second, the example code blocks should be in a fixed width font so that the decimal point aligns, but Qt Assistant is using a variable width font.  I found in preferences a way to set the font, but it seemed to apply globally.  If I want the code blocks to look okay then I need to accept that all the text is in fixed with font.  Interestingly, this is not the case for the pure HTML documentation which gets this right.

Third, there is an annoying extra colon before every function.  For example,

: mean (x)
: mean (x, dim)
: mean (x, opt)
: mean (x, dim, opt)

This is no worse than the HTML documentation that also has this defect, but it looks weird.  I suppose we should fix that and have the effect ripple through to the derived formats.

To me this is pointing towards making the HTML better and using a Qt widget that can display that, unless someone sees an easy fix for fonts in Qt Assistant.

Rik <rik5>
Project Administrator
Thu 01 Feb 2018 10:27:01 AM UTC, comment #10: 

I just wanted to add arguments in favor of the use of the QtHelp framework:

  • very good search capabilities (clucene beind the hood) that can be complemented with our "lookfor" function
  • Doxygen can directly generate the xml files needed by qcollectiongenerator (see e.g. https://doc.qt.io/archives/qq/qq28-qthelp.html). We could then have the C++ API documented in the GUI.
  • The documentation of octave forge packages could even be added if the package provides the xml files.
Pantxo Diribarne <pantxo>
Project Member
Wed 31 Jan 2018 03:18:39 PM UTC, comment #9: 

I attached the latest version of the python html parser so that it can serve as an example for a rewrite in whatever language (including python since I am far from fluent in this language).
The workflow for preparing a qhc file is to copy the python script in the parent directory of octave.html, cd into that directory and then run:

python prepare_qhelp.py octave_qhelp octave.html
qcollectiongenerator octave_qhelp.qhcp -o octave_qhelp.qhc

You now have a qhc file that can be used in assistant to see the full browse/search capabilities of the QtHelp framework

assistant -collectionFile ./octave_qhelp.qhc

Or you can look at the simple python script  (based on PyQt4, mostly borrowed on SO IIRC) attached to see how easy it is to create a browser on those qhc files.

python octave-pydoc.py

The search capabilities still have to be added but I think it should not be very hard.

(file #43139, file #43140)

Pantxo Diribarne <pantxo>
Project Member
Wed 31 Jan 2018 07:13:56 AM UTC, comment #8: 

>> Python is not yet a dependency ...

Considering we use Mercurial, isn't Python already a "hidden" dependency ?

Anyway I have nothing against the parser being rewritten in Perl (by someone else :-).

Pantxo Diribarne <pantxo>
Project Member
Wed 31 Jan 2018 01:46:27 AM UTC, comment #7: 

I'm just going with my recollection.  From what I remember Qt has its qt-assistant which is something very similar to the classic Windows documentation browser.  I think what it offers over, say, fundamental HTML is a search engine that will provide a list of quick links to locations where the searched-for word is found.  I programmed something like that for gnuplot's Qt terminal.  I like it, it's fast response/rendering (unlike HTML which has to do a lot of parsing of formatting words) and convenient search.

However, Qt also has basic HTML support within a Qt frame, so I think one just needs to feed such a Qt object the HTML code and it will behave somewhat similar to a web browser.  In other words, the HTML code posted here:


could be piped into a resident window.  In other words, similar content and appearance in both Help::Documentation::On_Disk and Help::Documentation::Online.

Dan Sebald <sebald>
Wed 31 Jan 2018 01:12:41 AM UTC, comment #6: 

I don't see any problem with generating more help files and putting them in to the tarball for distribution.  As long as the pain of generation (if there is any pain) falls on developers, rather than users, it should be fine.

Python is not yet a dependency, so I'd prefer not to add it.  Perl is still a dependency so we could use that if necessary and I am very fluent in that language.  Otherwise, doing it in Octave would be wonderfully self-contained.  Octave regexp are pretty powerful since they are based on the Perl Compatible Regular Expression (PCRE) library.  But I agree with the general web concensus that if the particular parsing is really complex we would be better off doing it in a language designe for text manipulation like Perl rather than Octave which is meant for manipulating numbers. 

Rik <rik5>
Project Administrator
Tue 30 Jan 2018 10:03:49 PM UTC, comment #5: 

There has been a discussion here about using the html version of the manual together with Qt Help framework:


Basically, I wrote a python script that parses the html manual and generates xml files that are read by qcollectiongenerator to produce a qhc file (qt help collection). Then one can use the QtHelp framework to index the manual and show pages in a simple QTextEdit widget.

Pantxo Diribarne <pantxo>
Project Member
Tue 30 Jan 2018 12:23:43 AM UTC, comment #4: 

Okay, I'm fine with HTML then as that seems to be the path of least effort.

Rik <rik5>
Project Administrator
Mon 29 Jan 2018 11:23:50 PM UTC, comment #3: 

Yes, Qt has good HTML support.  It's a special type of window/frame/widget derived from more generic widgets.  I've used this support before, but can't recall when:


I can't recall any type of PDF support for Qt, at least not by the development team.  Part of the reason might be that PDF is an Adobe definition, not a more ubiquitous standard.  For that, it might be a case of just embedding some type of PDF viewer within a Qt shell of sorts.

Dan Sebald <sebald>
Mon 29 Jan 2018 10:36:02 PM UTC, comment #2: 

If there is a native PDF viewer for Qt that would be ideal.  The typeset TeX display of mathematical formulas is very good in the PDF document.  But, failing that, HTML would be good as well.  Qt must have an HTML viewer.

Rik <rik5>
Project Administrator
Mon 29 Jan 2018 10:22:58 PM UTC, comment #1: 

The documentation browser just sucks.  I think we should replace it, either with an HTML browser widget or PDF file viewer widget.  I think that would be a much better use of time than trying to fix the info browser thing.

John W. Eaton <jwe>
Project Administrator
Mon 29 Jan 2018 10:12:23 PM UTC, original submission:  

The index chapters of the manual, such as the function index, are displayed strangely in the Documentation Browser which is embedded in the GUI.

Steps to Reproduce:

# Click on Documentation Tab
# Scroll down, Click on Function Index

The displayed result starts with

» accumarray.       (line   10)
» accumarray <1>.       (line   11)
» accumdim.       (line  101)
» acos.       (line  108)
» acosd.       (line  260)
» acosh.       (line  171)
» acot.       (line  128)
» acotd.       (line  286)
» acoth.       (line  191)
» acsc.       (line  123)
» acscd.       (line  281)
» acsch.       (line  186)
» addlistener.      (line  122)

The line numbers are meaningless, and don't need to be included.  They are not present in the general HTML documentation in the octave.html directory.

Rik <rik5>
Project Administrator


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

Attach Files:

Attached Files
file #45407:  53006.patch added by rik5 (1KiB - text/x-patch)
file #45404:  screen1.png added by sschoeps (108KiB - image/png)
file #45405:  screen2.png added by sschoeps (86KiB - image/png)
file #43882:  Ragged_Edge_Doc.png added by rik5 (214KiB - image/png)
file #43779:  offlinecss.patch added by pantxo (3KiB - text/x-patch)
file #43725:  registerdoc4.patch added by pantxo (14KiB - text/x-patch)
file #43724:  query_widget_qt-5-9.patch added by ttl (4KiB - text/x-patch)
file #43718:  registerdoc3.patch added by pantxo (13KiB - text/x-patch)
file #43715:  registerdoc.patch added by pantxo (11KiB - text/x-patch)
file #43713:  bug53006_ttl_v02.patch added by ttl (17KiB - text/x-patch)
file #43697:  bug53006_ttl_v01.patch added by ttl (12KiB - text/x-patch)
file #43693:  bug53046_ttl_01.patch added by ttl (751B - text/x-patch)
file #43267:  add_qch_qhc.patch added by pantxo (9KiB - text/x-patch)
file #43259:  prepare_qhelp.py added by pantxo (6KiB - text/x-python)
file #43139:  prepare_qhelp.py added by pantxo (5KiB - text/x-python)
file #43140:  octave-pydoc.py added by pantxo (2KiB - text/x-python)


Depends on the following items: None found

Items that depend on this one: None found


Carbon-Copy List
  • -email is unavailable- added by sschoeps (Posted a comment)
  • -email is unavailable- added by mmuetzel (Posted a comment)
  • -email is unavailable- added by godfrey (Posted a comment)
  • -email is unavailable- added by ttl (Posted a comment)
  • -email is unavailable- added by pantxo (Posted a comment)
  • -email is unavailable- added by sebald (Posted a comment)
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by rik5 (Submitted the item)

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.




    Follow 25 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-11-13 rik5 StatusIn Progress => Fixed
        Open/ClosedOpen => Closed
    2018-11-11 rik5 Attached File- => Added 53006.patch, #45407
    2018-11-11 mtmiller Carbon-CopyRemoved 80942 => -
    2018-11-11 sschoeps Attached File- => Added screen1.png, #45404
        Attached File- => Added screen2.png, #45405
    2018-04-11 sebald Attached File- => Added documentation_example_highlighting_Screenshot_from_2018-04-11_14-36-05.png, #43883
    2018-04-11 rik5 Attached File- => Added Ragged_Edge_Doc.png, #43882
    2018-04-05 sebald Attached File- => Added octave-documentation_standard_bindings-djs2018apr05.patch, #43812
    2018-04-04 sebald Attached File- => Added octave-documentation_inpage_find-djs2018apr03.patch, #43792
    2018-04-03 pantxo Attached File- => Added offlinecss.patch, #43779
    2018-03-30 pantxo Attached File- => Added registerdoc4.patch, #43725
    2018-03-30 ttl Attached File- => Added query_widget_qt-5-9.patch, #43724
    2018-03-29 pantxo Attached File- => Added registerdoc3.patch, #43718
    2018-03-29 pantxo Attached File- => Added registerdoc.patch, #43715
    2018-03-29 sebald Attached File- => Added missing_from_acoth_search_Screenshot_from_2018-03-29_00-37-41.png, #43714
    2018-03-28 ttl Attached File- => Added bug53006_ttl_v02.patch, #43713
    2018-03-27 ttl Attached File- => Added bug53006_ttl_v01.patch, #43697
    2018-03-27 ttl Attached File- => Added bug53046_ttl_01.patch, #43693
    2018-02-12 pantxo Attached File- => Added add_qch_qhc.patch, #43267
    2018-02-12 pantxo Attached File- => Added prepare_qhelp.py, #43259
    2018-02-09 rik5 StatusConfirmed => In Progress
    2018-01-31 pantxo Attached File- => Added prepare_qhelp.py, #43139
        Attached File- => Added octave-pydoc.py, #43140
    2018-01-29 rik5 StatusNone => Confirmed

    Back to the top

    Powered by Savane 3.5