Doxygen version

[Randalph]

The contributing guidelines for modifying class documentation don't specify what version of doxygen to use. I blithely downloaded the latest version and ran it (1. 9.4). While technically it worked, there were definitely issues. The xrc_format.h file I modified started off fine, and then switched to bold text after every table. I tried generating a CHM file, but a lot of the resulting files generated script errors when displayed in HTML Help. Both problems went away when I switched to the 1.8.17 version that the github build script is using. Anyway, I wanted to mention it because while the bold text issue was easy to spot, the issue with the CHM files would be easy to miss.

I'm wondering if it makes sense to at least mention in the adding documentation file what build version is currently being used, and perhaps indicate that the most recent version of Doxygen might not work correctly. Of course that means changing that file if the build version does get updated which would be easy to miss.

[Vadim Zeitlin]

On Wed, 25 May 2022 14:29:14 -0700 Randalph wrote:

R> The contributing guidelines for modifying class documentation don't specify
R> what version of doxygen to use. I blithely downloaded the latest version
R> and ran it (1. 9.4). While technically it worked, there were definitely
R> issues. The xrc_format.h file I modified started off fine, and then
R> switched to bold text after every table.

Is this another Doxygen bug or are we really doing something wrong here?
In any case, this is bad news because I hoped to switch to 1.9.x before
3.2.0, see https://github.com/wxWidgets/wxWidgets/issues/18849, but now
looks like there are even more problems with it than what I had already
found. I do appreciate what Doxygen does, but it's exceedingly painful that
its each new version seems to break something new...

R> I'm wondering if it makes sense to at least mention in the adding
R> documentation file what build version is currently being used, and perhaps
R> indicate that the most recent version of Doxygen might not work correctly.
R> Of course that means changing that file if the build version does get
R> updated which would be easy to miss.

We do have a check for Doxygen version in docs/doxygen/regen.sh which is
what should normally be used for generating the documentation. But perhaps
we need to document that this file must be used more prominently...

Regards,
VZ

[Randalph]

I skipped over the Unix directions which specify regen.sh, and went straight for the Windows directions which run regen.bat which in turn does not include any version information.

Since issues do seem to crop up with version changes, changing the docs to suggest using a matching version instead of a recent version would avoid some of the confusion. That and updating the actual version currently in use (1.8.17, not 1.8.8). I'll work on the wording and propose a change. I'm not terribly familiar with css, but I'm now setup fairly well to compare the differences between the two outputs, so I'll see if I can spot the problem with the tables. I suspect the issue with the script error is attempting to access the internet -- that's not allowed by HTML Help unless the file has been registered as safe. That means a doxygen-generated script change, since 1.8.17 doesn't have that issue. First, though, I want to figure out exactly what the issue is -- a script accessing the internet is exactly why Microsoft doesn't allow it by default -- too great a chance for malware to be inserted into the file. Anyways, I'll do more investigating and follow up here or on issue #18849. 

[Vadim Zeitlin]

On Wed, 25 May 2022 19:40:52 -0700 Randalph wrote:

R> I skipped over the Unix directions which specify regen.sh, and went
R> straight for the Windows directions which run regen.bat which in turn does
R> not include any version information.

Unfortunately .bat is pretty limited. I guess we could have a PowerShell
script for MSW instead of this one by now, but OTOH it might be better to
just ask people to use bash there too, it's not like it's very difficult to
do it neither.

R> Since issues do seem to crop up with version changes, changing the docs to
R> suggest using a matching version instead of a recent version would avoid
R> some of the confusion. That and updating the actual version currently in
R> use (1.8.17, not 1.8.8). I'll work on the wording and propose a change. I'm
R> not terribly familiar with css, but I'm now setup fairly well to compare
R> the differences between the two outputs, so I'll see if I can spot the
R> problem with the tables. I suspect the issue with the script error is
R> attempting to access the internet -- that's not allowed by HTML Help unless
R> the file has been registered as safe.

It really shouldn't be necessary... Please let us know if you can find out
why does it try to access the network in the first place.

R> That means a doxygen-generated script change, since 1.8.17 doesn't have
R> that issue. First, though, I want to figure out exactly what the issue
R> is -- a script accessing the internet is exactly why Microsoft doesn't
R> allow it by default -- too great a chance for malware to be inserted
R> into the file. Anyways, I'll do more investigating and follow up here or
R> on issue #18849.

This would be great, TIA!
VZ

[Randalph]

Doxygen 1.9.4 is when the generated CHM index file (index.hhk) changed to pick up all constructors, and also added some script that generates script errors in some of the topics. Building with Doxygen 1.9.3 doesn't cause either problem.

That's the good news. However, 1.9.3 does still have the problem with paragraphs becoming bold in overview_xrcformat.html (tested on both firefox and chrome). An even worse problem is overview_resyntax.html where the doxygen parser gets confused and generates most of the content in its raw form without line breaks (snippet below)

Class-shorthand escapes (AREs only) provide shorthands for certain commonly-used character classes: <table class='doctable' border='1' cellspacing='0' cellpadding='3'> <tr><td> <tt>@\d</tt> </td> <td> <tt>[[:digit:]]</tt> </td></tr> <tr><td> <tt>@\s</tt> </td>

There are four .h files in the overviews directory that contain @beginTable, but only two of them exhibit problems. Randomly jumping to a few other overviews, I'm not seeing other issues, so I still don't know if this is a problem isolated to two files, or a more general issue. If it's related to @beginTable, then it may be simply a matter of finding out what's breaking the parser, and changing the files to work around it. I'll be trying that once I've looked at a lot more files to check for problems.

Assuming a fix for the 1.9.3 overview files can be found, maybe just change the contributing docs to say "Doxygen 1.9.4 is evil when generating CHM files!" 😁

[Ian McInerney]

Out of curiosity, do you see this issue still on the new Doxygen version: https://github.com/wxWidgets/wxWidgets/pull/2367#issuecomment-851025935? It is another weird one I couldn't figure out at the time.

-Ian

--
You received this message because you are subscribed to the Google Groups "wx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to wx-dev+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/wx-dev/CAHmEKeqRX6%3DwL61XDBx4adxGkxvana%3DCd2UDpFUmS4h4XzGvmw%40mail.gmail.com.

--

Ian McInerney
mcia...@gmail.com

No electrons were harmed in the making of this message

[Randalph]

I looked at doxygen-generated out/html/page_screenshots.html generated by 1.8.17, 1.9.3, and 1.9.4 and it looks fine in all three versions.

To view this discussion on the web visit https://groups.google.com/d/msgid/wx-dev/CACp%3DVfZyDm3BTO1VCb0Yod4CqHziv7qh8kgP4-yxTgqqM_QeMg%40mail.gmail.com.

[Randalph]

Doxygen 1.9.4 changes the way the top menu is displayed (both in web and CHM) and it appears this is where the breakage occurs in the CHM file.

This is how it looks in 1.9.3:

And this is how it looks in 1.9.4:

[Vadim Zeitlin]

On Thu, 26 May 2022 08:42:18 -0700 Randalph wrote:

R> Doxygen 1.9.4 is when the generated CHM index file (index.hhk) changed to
R> pick up all constructors, and also added some script that generates script
R> errors in some of the topics. Building with Doxygen 1.9.3 doesn't cause
R> either problem.

Hello again,

One of the main things I'd like to do before 3.2.0 is to improve the
appearance of our documentation (improving their contents would be great
too, but I'm choosing the easier task), probably by starting to use the
doxygen-awesome-theme, see https://github.com/wxWidgets/wxWidgets/issues/18849
(I hate "awesome" in the name, but it does look better than the currently
being used one).

And so we need to choose the Doxygen version and I'm still not sure which
one should we use. Have you been able to find anything more about the
issues you've seen? Perhaps we could use an even earlier 1.9.x version, or
are they as broken as 1.9.3?

Thanks in advance!
VZ

[Randalph]

I've updated the issue indicating that the formatting problem has been fixed for all versions that I tested (through 1.9.4). There is a change to all HTML pages in 1.9.4, but depending on what the theme does, that may be moot.

The CHM problem with 1.9.4 is more significant -- but since Doxygen maintains older versions, one could always suggest for the holdouts (like me 😁) that still use CHM files that they could simply install 1.9.3 and build the CHM file themselves (which is what I now do).

[Vadim Zeitlin]

On Mon, 6 Jun 2022 16:26:07 -0700 Randalph wrote:

R> I've updated the issue indicating that the formatting problem has been
R> fixed for all versions that I tested (through 1.9.4). There is a change to
R> all HTML pages in 1.9.4, but depending on what the theme does, that may be
R> moot.

Great to hear, thanks! I'll try using the custom theme with 1.9.3 a.s.a.p.
then (maybe not immediately though, as I have to work on some other things
now that 3.1.7 is done).

R> The CHM problem with 1.9.4 is more significant -- but since Doxygen
R> maintains older versions, one could always suggest for the holdouts (like
R> me 😁) that still use CHM files that they could simply install 1.9.3 and
R> build the CHM file themselves (which is what I now do).

As long as we provide CHM files as part of the release, we need to use a
Doxygen version which generates it correctly. Which is, in fact, the main
reason I'd like to drop it -- it's not that I don't like CHM itself, but
the fact that it can only be generated from a Windows system using an
ancient tool is rather bothersome and I definitely don't like this.

BTW, does anybody know what are "modern" Windows applications supposed to
use for their offline help? CHM has been deprecated since ages, but there
doesn't seem to be any real replacement for it from Microsoft, is there?

Regards,
VZ

[Kenneth Porter]

On 6/6/2022 4:59 PM, Vadim Zeitlin wrote:
> BTW, does anybody know what are "modern" Windows applications supposed to
> use for their offline help? CHM has been deprecated since ages, but there
> doesn't seem to be any real replacement for it from Microsoft, is there?

Is there any active server-side content that requires an active format?
I've been hosting a copy of the generated HTML and CSS for viewing in
Chrome or Firefox and that seems sufficient.  Am I missing anything by
doing that? I suppose it's harder to transport/copy than a single file
but I haven't needed to do that.

[Randalph]

The demand for off-line help is too low for it to be worthwhile for Microsoft's Windows division to create a team again to create an offline help system.

wxWidgets already has an effective replacement for the CHM file format -- CHM is just a document storage system using a different compression system than zlib. What's lacking is an index and full text search. There's no standard HTML tag for an index entry, which is why the current wx.chm index is so problematic. It's auto-generated from content that does not specify what an index entry should be. That makes a good index UI rather problematic to do. There's lots of search engines out there, but they are designed to work on the web -- developing a good full text search system that only works on a zlib storage system would be a lot of work. Aside from those two missing components and a "compiler" to pull all of the content together, the helpview utility could probably be upgraded to provide a cross-platform off-line system for accessing wxWidgets documentation.

--
You received this message because you are subscribed to the Google Groups "wx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to wx-dev+un...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/wx-dev/53372b14-e2b2-c435-95d9-d1584bebe71c%40sewingwitch.com.