@seealso links in documentation now work for old-style classes (e.g., @ftp)

First, the good news. It is now possible to add @seealso links in the documentation to old style classes such as @ftp or @audiorecorder. See changeset octave: 0ef88c485786

The links show up correctly in “plain text” format such as when using help XXX in a command window. They also show up properly in the PDF manual and correctly hot link between sections of the manual.

Second, the bad news. I haven’t quite got doc XXX to work. I could use some help here as it is probably a simple matter of adjusting the search term specified to match the @anchor field in the Texinfo documentation.

For a test case, try ‘doc @ftp/close’. This opens up a GUI documentation browser which says

The node you are looking for is at XREF@ftp/close.

If I then click on the hot link (XREF@ftp/close) it takes me to the correct location in the manual.

So, the behavior is very close to desired, but I don’t want to have to go through the intermediate screen and have to click on the link.

Unfortunately for me, I don’t know the libgui code well enough to determine where I could make a change to the search term in order to have it match what is in the GUI documentation index.

I can confirm that message on my system (mint 20.2), but if I click on the provided link, it leads me to the beginning of the the html page, FTP-Objects.html, while I would expect to see the close method definition on the first line (at the FTP-Objects.html#0004ftp_002fclose anchor).

It looks like for some reason the @seealso links (no only those in the ftp class) don’t work correctly either: clicking any of them always gets me to the beginning of the page.

I could verify using qt’s assistant that our compressed help files, octave_interpreter.qch, is not at fault (the links lead to the correct location, as in the original html version). Is is only me seeing that regression?

Maybe? I’m running Kubuntu 18.04 with Qt-5.9.5. It is possible be that newer Qt versions actually behave worse.

What about the links that are created in either octave.pdf or in the HTML files in doc/interpreter/octave.html/FTP-Objects.html? Do these links work so it is really only the GUI documentation browser that is not working?

I have the same issue as Panxo on Fedora 35 and Ubuntu 20.10 (both have Qt 5.15.2)
Links in html and pdf seem to work correctly.

With Dmitri confirming, this seems to be a new, and worse, behavior for Qt.

If I had to make a guess, I would say that Qt is stopping parsing of the XREF when it sees the ‘/’ character. The forward slash ‘/’ is usually a delimiter and so XREF@@ftp/close is becoming XREF@@ftp which is why it goes to the start of the page rather than to the @anchor that it should.

But it works as expected on Centos 8, where qt is also 5.15.2 but some other libraries are older…

OK – it looks like it is texinfo. Fedora 65 has texinfo 6.8 and Centos has texinfo 6.5
After I “upgraded” Centos’ texinfo to 6.8 it broke the help there as well.

And “downgrading” it back to 6.5 (and rebuilding octave’s doc) fixes help again.

1 Like

Good docs (built with texinfo 6.5):

Bad docs (built with texinfo 6.8):

A quick comparison of the source html shows that, the XREF anchor to function definition in html source files is a <span> in recent versions of texinfo (I have 6.7 and obtain the same as Dmitri with 6.8), while it used to be a hyperlink <a> element.

Both types of elements are supported by Qt text browser so there is nothing fundamental preventing the new html pages from being displayed properly. And actually, as I said previously, Qt’s assistant, which is basically the same as our doc browser, does handle our octave_interpreter.qch (seealso links work as expected), whether it is generated from old or new texinfo html pages.