Using Qt help framework

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Using Qt help framework

Pantxo
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

octave_help.qhcp (458 bytes) Download Attachment
octave_help.qhp (271K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Using Qt help framework

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



Reply | Threaded
Open this post in threaded view
|

Re: Using Qt help framework

Pantxo
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


Reply | Threaded
Open this post in threaded view
|

Re: Using Qt help framework

Pantxo
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 <[hidden email]>:
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 (6K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Using Qt help framework

Daniel Sebald
On 01/18/2016 06:33 AM, Pantxo Diribarne wrote:

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

The assistance can be controlled from within the Qt GUI as well:

http://doc.qt.io/qt-4.8/assistant-custom-help-viewer.html#using-qt-assistant-remotely

Dan

Reply | Threaded
Open this post in threaded view
|

Re: Re: Using Qt help framework

Pantxo
Le 18/01/2016 23:43, Daniel J Sebald a écrit :

> On 01/18/2016 06:33 AM, Pantxo Diribarne wrote:
>
>> Then you can browse/search the manual in qt-assistant using
>> assistant -collectionFile octave_qhelp.qhc
>
> The assistance can be controlled from within the Qt GUI as well:
>
> http://doc.qt.io/qt-4.8/assistant-custom-help-viewer.html#using-qt-assistant-remotely 
>
>
> Dan
>
>
Yes, this is the most economic approach and will provide almost every
search/browse features that we may want. This would make us have to
distribute qt-assistant. I am under the impression that anyway if we
ever want to integrate octave-forge function reference on a per
installed package basis, we will need to distribute qcollectiongenerator.
As I have very few time currently (an poor Qt knowledge) I can't propose
to implement a custom viewer my self but anyway, lets dream.  Among the
things we could do with a custom viewer:
* select a code snipet in the manual and run it in the interpreter using
a simple context menu. Yes, copy/paste is also a solution.
* use short-cuts that comply with the rest of the gui.
* tweak the way search results are displayed. For example Qt has two
separate widgets for index search and full text search, and we may want
to display both search results on the same page. Say I am looking for
doc on "integrate" keyword. We could first run "lookfor ('run')" which
would return a few Octave function names that have "integrate" in the
first sentence of the help string. Then I can display first the result
of an index search on all those functions (Function reference) followed
by full text search results.


Pantxo