Qhelpgenerator debug mode

[ferdymercury]

Describe the bug
Not a bug.

Expected behavior
It would be nice if, when -d qhp is enabled, qhelpgenerator is run first (twice) with the flags -v -c, which print the version and check that all files from the file list are found. (I think they cannot be used simultaneously, nor with -o).

To Reproduce
See the reproducer at #9094

Screenshots

Usage:

qhelpgenerator <help-project-file> [options]

  -o <compressed-file>   Generates a Qt compressed help
                         file called <compressed-file>.
                         If this option is not specified
                         a default name will be used.
  -c                     Checks whether all links in HTML files
                         point to files in this help project.
  -v                     Displays the version of 
                         qhelpgenerator.

Version
1.9.4 (15dae50*)

Additional context
Included HTML path problems found in #9094

[albert-github]

As is the idea is sympathetic (and not difficult to implement) though I tried to run the -c option on the mentioned case and it takes ages (runs already over 20 minutes at my place).

The documentation states:

Checks whether all links in HTML files point to files in this help project.

I think one can either interpret this as:

• checks whether all files mentioned in the index.qhp exist

or

• checks whether all files mentioned in the index.qhp exist and all links in the mentioned files exist.

It looks to me that the later is done here.

So I don't think it is a good idea to run the -c even under debug conditions.

Regarding the -v I'm not sure this is something doxygen should output either, though with the -d qhp this would be easy again.

• how fast did you see the results of the -c?
• @doxygen what to do?

Did you miss some files in the example besides the files in the "user" : of the layout files (i.e. "group__Tutorials.html" and "release-notes.html")

[ferdymercury]

Thanks for the reply!

With the root-docu "reproducer" I linked, the -c option runs in less than a second for me. Weird...

root-docu/documentation/doxygen/html$ time qhelpgenerator index.qhp -c

real	0m0,020s
user	0m0,012s
sys	0m0,008s

I am using:

qhelpgenerator -v
Qt Help Generator version 1.0 (Qt 5.15.2)

To test that it's working, go to the html output folder, and remove index.html
Then if you rerun qhelpgenerator index.qhp, you will get:

time qhelpgenerator index.qhp -c
Warning: File "index.html" does not exist.

real	0m0,015s
user	0m0,004s
sys	0m0,011s

Concerning what this option does, yes, it's a bit ambiguous. I think it only checks that the files listed in the XML file index.qhp do exist. Those between the <files> tags.

<files>
<file>tabs.css</file>
<file>tab_a.png</file>
<file>tab_b.png</file>
<file>tab_h.png</file>
<file>tab_s.png</file>
<file>nav_h.png</file>
<file>nav_f.png</file>
<file>bc_s.png</file>
<file>doxygen.svg</file>
<file>closed.png</file>
<file>open.png</file>
<file>bdwn.png</file>
<file>sync_on.png</file>
<file>sync_off.png</file>
<file>nav_g.png</file>
<file>doxygen.css</file>
<file>jquery.js</file>
<file>dynsections.js</file>
<file>svgpan.js</file>
<file>search/search_l.png</file>
<file>search/search_m.png</file>
<file>search/search_r.png</file>
<file>search/close.svg</file>
<file>search/mag_sel.svg</file>
<file>search/search.css</file>
<file>search/search.js</file>
<file>doc.png</file>
<file>folderopen.png</file>
<file>folderclosed.png</file>
<file>splitbar.png</file>
<file>TAtt3D_8h_source.html</file>
<file>TBase64_8h_source.html</file>
<file>TAtt3D_8cxx_source.html</file>
<file>TBase64_8cxx_source.html</file>
<file>TAtt3D_8h.html</file>
<file>TBase64_8h.html</file>
<file>TAtt3D_8cxx.html</file>
<file>TBase64_8cxx.html</file>
<file>mainpage_8md.html</file>
<file>classTAtt3D.html</file>
<file>classTAtt3D-members.html</file>
<file>classTBase64.html</file>
<file>classTBase64-members.html</file>
<file>dir_b952992678633ce5ff96b3ca450b719d.html</file>
<file>dir_4270bfced15e0e73154b13468c7c9ad9.html</file>
<file>dir_096f11663d5b0df5875ce3388f5709f9.html</file>
<file>dir_eebeeb11555a5e66c87b76692c0b7aac.html</file>
<file>index.html</file>
<file>annotated.html</file>
<file>classes.html</file>
<file>functions.html</file>
<file>functions.html</file>
<file>functions.html</file>
<file>functions.html</file>
<file>functions.html</file>
<file>functions_func.html</file>
<file>functions_func.html</file>
<file>functions_func.html</file>
<file>functions_func.html</file>
<file>functions_func.html</file>
<file>files.html</file>
<file>globals.html</file>
<file>globals.html</file>
<file>globals.html</file>
<file>globals_func.html</file>
<file>globals_func.html</file>
<file>globals_func.html</file>
</files>

Yes, the files groupTutorials and release-notes are missing because I trimmed the full example to a minimum reproducer, but did not bother to update the DoxygenLayout file.

[albert-github]

I tried:

• 6.1.2 and this has the behavior as indicated
  • did also do the test without the index.html and in that case it quickly shows that the index.html is missing and after this it looks like it is in an end less loop or doing some very long lasting operations
• 6.2.2 and this also takes ages
• 5.15.2 runs fast though
  • as you mentioned doesn't warn at all for the groupTutorials and release-notes, so looks indeed like it is not looking at the <toc> part.

So I'm still think it is not wise to enable the -c flag in debug mode.

[ferdymercury]

Hmmm looks that the newer qhelpgenerator is buggy then. This is a small project file, so even when recursing links, it should finish in a couple of seconds. Agreed, let's skip this then. Or we can leave it open for the moment and submit a bug report to Qt.

[albert-github]

Best would indeed that you submit a bug report to Qt (and post a link here).
Might be that they could also explain / enhance a bit about what is checked.

[ferdymercury]

Good point, thanks. Here the link: https://bugreports.qt.io/browse/QTBUG-101070

[ferdymercury]

A patch has been proposed https://codereview.qt-project.org/c/qt/qttools/+/400691

[ferdymercury]

Patch has been released for 6.4.0 Alpha (as well as for 6.3.0 RC and 6.2.5)

[albert-github]

I've just pushed a proposed patch, pull request #9228

[ferdymercury]

Thanks!!

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.9.4.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).