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: GUISeverity: 3 - Normal
Priority: 5 - NormalItem Group: Feature Request
Status: In ProgressAssigned to: None
Originator Name: Open/Closed: Open
Release: devOperating 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 Jump to the original submission)

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:
  • 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:

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

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,

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:

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

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.

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:

https://www.gnu.org/software/octave/doc/interpreter/index.html

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:

http://octave.1599824.n4.nabble.com/Using-Qt-help-framework-td4674409.html#a4674410

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:

http://doc.qt.io/qt-5/qtextbrowser.html
http://doc.qt.io/qt-5/qtextdocument.html#setHtml
http://doc.qt.io/qt-5/qtextedit.html#html-prop
http://doc.qt.io/qt-5/qwebenginepage.html

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:

The displayed result starts with

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 File(s):
   
   
Comment:
   

Attached Files
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
  • -unavailable- added by ttl (Posted a comment)
  • -unavailable- added by pantxo (Posted a comment)
  • -unavailable- added by sebald (Posted a comment)
  • -unavailable- added by jwe (Posted a comment)
  • -unavailable- added by rik5 (Submitted the item)
  •  

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

    Only project members can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 6 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Mon 12 Feb 2018 10:57:37 PM UTCpantxoAttached File-=>Added add_qch_qhc.patch, #43267
    Mon 12 Feb 2018 12:19:05 PM UTCpantxoAttached File-=>Added prepare_qhelp.py, #43259
    Fri 09 Feb 2018 11:24:49 PM UTCrik5StatusConfirmed=>In Progress
    Wed 31 Jan 2018 03:18:39 PM UTCpantxoAttached File-=>Added prepare_qhelp.py, #43139
      Attached File-=>Added octave-pydoc.py, #43140
    Mon 29 Jan 2018 10:36:02 PM UTCrik5StatusNone=>Confirmed

    Back to the top


    Powered by Savane 3.1-cleanup1