#707 Html help/doc via GUI terminal
There was mention in another patch thread
https://sourceforge.net/p/gnuplot/patches/704/
about integrating gnuplot's help as a HTML resource into the WXT terminal. I've tried this with some positive preliminary results (but I'm not yet familiar with the docs material) so this is a new thread to follow through on developing the notion. I also notice there are all kinds of figures that are processed (and failed), but I think those might be the demo examples.
What I've done is run "make html" in the source tree and the result is a ./docs/htmldocs/gnuplot.html along with many supporting files in the directory. Upon pressing the "about" button (with the question mark graphic) I've created a simple HTML window and loaded this file using the full directory path. Attached is a low-res screen shot of the result. The HTML paths all seem to work fine.
I'm not sure if this is the material that was being asked about. Does this look like the right idea? Does the window need to be embellished in some way? What about the "about" button? Does that need to be enhanced so there is an "about" and a "help"? In the wxWidgets documentation there is same discussion about an even more feature-rich version of the "html help" window which supports Windows help format. I sort of recall this Windows help from once having done such a thing in the 1990s, but people will have explain a bit more what they have in mind. (Seems to require bundling all files into a zip file.)
The other part of this is that in order to get help available at the terminal, we need to put the HTML files somewhere on the system and have some mechanism within gnuplot for accessing that path. "make install-html" doesn't appear to do anything. Ethan can probably give some suggestions on how to install the help files and access gnuplot.html via C code.
Also, I believe Qt has similar mechanisms for HTML code and I will try to do parallel code in both WXT and Qt terminals at the same time.
This message was supposed to be attached to the previous thread. Sometimes the embedded text editor/interpretter becomes sluggish and behaves oddly. I must have pressed "Post" when the interpretter was busy.
Anyway, stopping at "OnHelp 15" means that the line
if (helpcontrol->AddBook(htbhelpfile)) {is hanging and suggests to me that something must be incorrect with the compressed help files. Does the following produce sane results as far as Zip files go (you'll have to change the path to suit your system)?
I'm seeing the following:
Archive: /usr/local/share/gnuplot/5.1/help/wx/gnuplot.htb testing: gnuplot.hhp OK testing: gnuplot.hhc OK testing: gnuplot.hhk OK testing: loc10001.html OK testing: loc10049.html OK ...Last edit: Dan Sebald 2015-10-20
ubuntu has qtcollectiongenerator in "qttools5-dev-tools".
Ethan, you are using Mageia, right?
Package qttools5-assistant?
Yes. qttools5-assistant. What an obvious name ;/)
I have it working on qt now. It's cute.
Questions:
What exactly is the browser-like window that it opens?
I was expecting the Home button on this [browser?] window to take me back to the top level of the documentation. Instead it fires up a new Chrome session (my default browser) in a different workspace altogether. Was that intended?
Similarly for clicking on a hyperlink to one of the demos. If this whateveritis can display the demo locally, I think that is preferable to firing up a separate browser to display it.
It seems to keep previous state somewhere, which has the odd result that if you start a new gnuplot session and hit the Help button, it opens up to whatever documentation section you were looking at last time. I think it would be better to start out cleanly at the top of the documentation tree.
It is a viewer in the fashion familiar to Windows known as a help book.
I suppose, but I myself wasn't sure what to do with some of the do-dad features so just picked some type of behavior. One can click on "gnuplot" in the "Contents" tab window, so I probably figured why duplicate behavior? On my system selecting home opens a browser window as well and loads http://www.gnuplot.info/. It can be changed.
Can you give an example of what link you are clicking? All the links I'm clicking on take me to another local category within the contents. Local first would be the preference.
OK, I see that now. It's probably just the first time the Qt Assistant appears after a new session. If the user closes the Qt Assistant but doesn't exit and then opens it again, I would think it should go back to the same help window. Does that seem correct?
I meant, is it built on webkit or something else that can act as a web browser? Or is it limited to handing off URLs containing http:// to a separate entity.
Sure. Navigate to the help section for "polar mode". Now click on the final bit of text where it says "see also polar demos". It opens a new browser.
I see the demo links. There is one in financebars help as well. I suppose all the demo links are going outside of the Qt Assistant. I assume that Qt Assistant (and probably the wxWidgets equivalent) first look to their internal list of HTML files and if the file name is not there then looks to the web.
I don't believe Qt Assistant is set up to view external conent within its borders, but I could be wrong. I mean, there are other similar tools for viewing web content within a Qt window, so it is probably a small step from there to Qt Assistant (i.e., they are probably built on the same classes).
Notice that the other links with Qt Assistant are files with local names, created by build process, e.g.:
It strikes me that the file names could be anything so long as they are properly referenced within the HTML code and packed within the gnuplot.qch file. It might be as simple as packing all the demo files within that gnuplot.qch file (without name changes). And, it might make sense to add a "Demos" category in the Contents tab that will open the main page within Qt Assistant, i.e.
but that file might need a name change because there is no actual file name as part of that address, just the directory.
When I have some free time this evening I'll see if I can include the demo files.
BTW, there is a setting in Qt Assistant under Edit:Preferences...:Options that allows changing behavior at startup. Unfortunately, the other option is to open a blank page, not the main page.
Last edit: Dan Sebald 2015-10-20
I haven't had time to look at this until about an hour ago. I thought I would just try in concept to make this work first. I did get the WXT help book to accept the HTML demos without too much effort. Attached is a screen shot of the finance.html demo displayed within the help book viewer. My screen is only moderately sized so this view isn't the best (just a minor issue right now).
However, some of the changes I made would need some work. First there is the building of the HTML demo display. That doesn't work right now in a non-source build directory and there doesn't seem to be any main level "make thisorthat" shortcut. So I had to go to the source directory, change to demo/html and type "make". That created the html files and png files.
So, I then copied those html and png files to build directory ./docs/wx/demo. After running "make htb" to create the zip file ./docs/wx/gnuplot.htb, I zipped the directory demo into the gnuplot.htb file. Then "make install-htb".
However, one issue was that the links were not correct. I had to go back to the original gnuplot.doc file and replace:
with
Repeat the process. Then the links worked within the WXT help book viewer, and the attached PNG screenshot is the result.
So, the summary is I would say the demos can be brought into the helpbook without much modification to demo HTML generation (it does add to the time it takes for the helpbook to load...but still not bad). However,
1) We need to be able to generate the HTML in the build directory.
2) We need some special treatment of the fixed remote links in the gnuplot.doc file. There already is special treatment for converting, say 'candlesticks' to loc3210.html. So, I can't imagine it is too difficult to process the links in gnuplot.doc, but I'm not quite sure how to do that just yet because I suspect those remote links need to be there for some previous use. The easiest thing is probably to replace any "http://www.gnuplot.info/" with "" in the links when generating helpbook-like files.
Last edit: Dan Sebald 2015-10-27
I don't like the idea of pre-building all the html demos and distributing them that way. I have always viewed that subdirectory as a convenience for the developers to update the web site, not as something the end users need to rebuild as web pages locally. If nothing else, the online demos are more likely to be up to date than ones that were pre-built for packaging 6 months or a year ago. So if the qt viewer can't handle external URLs then let's drop that idea.
I like the qt viewer, but still no luck at all with wxt. Did you have any other ideas to debug it?
OK, good point. I don't find it too inconvenient having the page open in an external browser, but It is sort of nice having the demos within help viewer. Nonetheless, being able to view the remote HTML content within the Qt/WXT viewer would be optimal. I'll look around a bit and see if that is possible. My guess is that the viewer can't assume that the web link is comprised of HTML code.
For WXT, did you try the things in this post:
https://sourceforge.net/p/gnuplot/patches/707/?limit=25&page=1#66f7/99c1/cd4e
I believe when I originally submitted that post I had lost the contents so it may have appeared blank initially. I later went back to fill in the post. Bascially, I just wanted to confirm that parts of the build are correct in order to find out exactly where things are going wrong.
In order to get a little more info on the WXT problem, I'll provide a link to the compressed zip file to replace the one that is generated on your system. The file works on my system, so this should help us identify if it is the building of the compressed zip file that is the problem, or if the code that loads the book is the problem.
Any chance to get a new patchfile against the current tree on this? It's just damn useful for day-to-day work. ;-)