Re: Using Qt help framework

[Pantxo Diribarne]

I attached a python script that generates the base xml files. The process is the same as before but  index.html and Function-Index.html are directly parsed using lxml.

You need to copy the script in the documentation directory (build/tree/doc/interpreter) and run the following commands:

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

Then you can browse/search the manual in qt-assistant using
assistant -collectionFile octave_qhelp.qhc

Pantxo

2016-01-17 16:31 GMT+01:00 Pantxo Diribarne <address@hidden>:

Le 17/01/2016 10:15, Torsten a écrit :

On 17.01.2016 09:40, Pantxo Diribarne wrote:

Hi,

I prepared the attached 2 xml files as a proof of concept for using the
Qt help framework to replace our current doc browser.

If you want to get a taste of what the doc browser could look like and
the features we could have access to, copy the 2 files in the same
directory as "octave.html" directory (build/tree/doc/interpreter) and
run the following commands in that directory:

qcollectiongenerator octave_help.qhcp -o octave_help.qhc
assistant -collectionFile octave_help.qhc

This will produce a self contained Qt Help Collection file and load it
into qt-assistant. We can virtually (with time and work as usual)
reproduce all the qt-assistant features/widgets behavior using Qt help
module [1].

In case you are interested to make the change in the future, the xml
files were prepared semi-automatically using java Xerces and HTMLCleaner
libraries. I had to parse only 2 files:
* "index.html" to retrieve the table of contents and corresponding html
links
* "Function-Index.html" to retrieve the function reference and
corresponding links

The above can probably be done using regexp in Octave, which would avoid
having to rely on new libraries.

Thoughts?

Pantxo

[1] http://qt.apidoc.info/4.8.5/qthelp.html#details

Pantxo, these are very good news and the documentation really looks good
in the Qt-Assistant browser. If it is possible to fully automate the
generation of the necessary files during the build process, we certainly
should use the Qt help framework instead of our current viewer with all
its limitations.

Torsten

I did most of the parsing in Octave using Xerces. The reason why I chose this lib is not sensible: this is the only xml library I happen to know a little and that works with Octave java support. As our documentation is in html, not xhtml and Xerces only handles xml, a first conversion/cleanup was necessary and for that I used HTMLCleaner library. Unfortunately I had to tweak a few things by hand (remove all "meta" elements) as even HTMLCleaner doesn't produce a file Xerces is able to parse for Function-Index.html.
For the definite automated way to do that I'd see a few options :
* python+lxml: much cleaner than Xerces+HTMLCleaner as lxml can parse html directly. I don't know if python is already  a developer dependency?
* pure Octave using regexp: I am not experienced in this area and  I don't know how robust such approach can be. At least I see a bunch of posts on stackoverflow that warn against such approach. Regexp gurus welcome ?

Pantxo

prepare_qhelp.py
Description: Text Data