Problem building documentation with Doxygen version ≥ 1.9.4

[ManoloFLTK]

A problem appears in the HTML documentation as built with Doxygen version 1.9.4 (today's most recent version of Doxygen is 1.9.5). The problem is in the table of contents appearing in the left panel of the HTML doc. These images show the situation with the problem (top: "FLTK programming manual" contains no sub-items) and with the proposed fix (bottom: sub-items appear) :

The proposed fix is to change line 3 of documentation/src/index.dox from
\mainpage FLTK Programming Manual
to
\page mainpage FLTK Programming Manual

I've checked the modified index.dox is OK with older versions of Doxygen (specifically 1.8.14 dated Jan 2018). I didn't consider pdf documentation.

Comments ?

[Albrecht-S]

That's weird: \mainpage is a valid doxygen command, see doxygen documentation. The docs say:

If the \mainpage command is placed in a comment block the block is used to customize the index page (in HTML) or the first chapter (in LaTeX).

You could argue that index.dox is not "a comment block" but I believe that this is probably a doxygen bug and will hopefully be fixed in a later version. I don't have the time to test right now but I can certainly build 1.9.4 and 1.9.5 to see what is happening with these version. Later.

The problem I can imagine with the proposed fix is that there won't be any hint to what should be the main (index) page in HTML and in PDF.

It's hard to say if we should change it or leave it as is and warn users not to build the docs with 1.9.4. Perhaps the bug is either fixed or already known to the doxygen folks?

@manolo Did you also test with 1.9.5?

That said, our GitLab mirror builds the doxygen docs (currently) with 1.9.1 which is good. IMHO versions 1.9.2 and 1.9.4 (likely also 1.9.3) are broken because the HTML class index has a new format (Manolo, can you please test and verify this?) that doesn't fit on the HTML page w/o horizontal scrolling to select any class beyond the first few classes. The old format until 1.9.1 (see docs at fltk.org and at our GitLab mirror) seems to be much better IMHO. I don't know why they changed this. :-(

[ManoloFLTK]

1.9.4 and 1.9.5 do the same thing. Thus, the change appeared with 1.9.4 was not reverted by 1.9.5. I'm not sure it's a Doxygen bug, and it seems it would be dangerous to bet it will be reverted.

My view now is that the proposed fix is useful because with it, resulting HTML pages are OK all the way from 1.8.14 to 1.9.5.

I've seen the new indices and don't like them at all. I'll search if there's an option to keep indices the old way.

[erco77]

Doxygen is on github, so you can open an issue if you can create "a, small, self contained example" demonstrating the problem:
https://github.com/doxygen/doxygen/issues

[erco77]

I can confirm this issue is still present with the latest build of doxygen from git 1.9.6 (01b73df835) and current fltk 1.4.x, so if it's an actual bug in doxygen, it should probably be reported using doxygen's issue page. The doxygen project has a few regressions, so it's entirely possible you've caught a regression bug.
The doxygen commit tree is very colorful -- reminds me of a subway map..!

[Albrecht-S]

@ManoloFLTK wrote:

… the proposed fix is useful because with it, resulting HTML pages are OK all the way from 1.8.14 to 1.9.5.

I disagree. The resulting index.html is not correct if you change '\mainpage ...' to '\page mainpage ...'. The menus are available (that's correct) but if you open index.html the view is different, it doesn't show the main page with all the chapters in the right panel.

Old view with \mainpage (as currently on GitLab, Doxygen 1.9.1):

Changed view with \page (Doxygen 1.8.17):

It is obviously essential to have a \mainpage command to populate index.html and/or (as the docs say) the first page of the PDF docs.

I'm trying to create a small example that shows the effect as a reproducer to file a bug report (GitHub issue) for Doxygen.

[Albrecht-S]

BTW: the PDF docs would be different as well. Please check yourself.

[ManoloFLTK]

@Albrecht-S OK. I agree \mainpage remains necessary.
Let's hope you can find a convincing reproducer and Doxygen will fix that.

[Albrecht-S]

FYI: I created GitHub issue doxygen/doxygen#9616 for Doxygen.

[Albrecht-S]

@ManoloFLTK wrote:

Let's hope you can find a convincing reproducer and Doxygen will fix that.

The author of the problematic commit replied quickly and classified it as "bug" which makes me hope that it can be fixed soon.

[ManoloFLTK]

🤞

[Albrecht-S]

This issue has been fixed upstream in doxygen/doxygen@c84ec66 (branch master) and will be in the next official release (supposedly 1.9.6).

I tested it and it worked well, although there's another regression (some bogus warnings) which I will report in another doxygen issue.

The consequence is that we should keep in mind that Doxygen 1.9.4 and 1.9.5 should not be used to generate the official FLTK documentation.

Closing this issue now as fixed.