Updated 1.4 online docs

[Albrecht Schlosser]

Hi devs (and others)

I updated the online docs of FLTK 1.4.0 (html and pdf) with the latest
Doxygen version 1.9.8.

https://www.fltk.org/doc-1.4/index.html
https://www.fltk.org/doc-1.4/fltk.pdf

Please check and report if anything seems to be wrong or missing.


Notes:

1. The new PDF docs are *MUCH* longer (more pages) and thus also larger
(~11 MB rather than 5-6 MB before). This is due to more "Files" docs and
also a much larger index, AFAICT.

2. The previous online doc versions were created by me with Doxygen
1.9.1. Intermediate versions (e.g. 1.9.4) produced a very ugly HTML
class index, and some versions were really buggy (I reported two bugs
that were fixed meanwhile - IIRC in 1.9.6). 1.9.8 looks fine at a first
glance (1.9.6 untested), hence I tried 1.9.8 for the new online docs.

3. Our GitLab mirror has recently been updated to use Doxygen 1.9.4 (we
use a CI build to update the docs daily), see for instance the old (IMHO
ugly) class index, particularly the four-letter shortcuts at the top
(you need to use the arrow keys or scrollbar to reach the the letters
above 'C', depending on your screen width).
See https://fltk.gitlab.io/fltk/classes.html

[Mo_Al_]

The theme is much better than the old one. 

I noticed that the index page has some color issues:

[Albrecht Schlosser]

On 9/4/23 13:40 Mo_Al_ wrote:

The theme is much better than the old one.

Thanks for your comments.

I noticed that the index page has some color issues:

Hmm, you seem to use a "dark theme" or some other personal browser settings. I can't reproduce this here:



Even if I change Firefox to use a dark theme, the contents stay the same.

Maybe you need to refresh the entire browser window (use Shift+RefreshButton) or you have some other issues with your browser. You could also try to use Firefox with a new profile (run `firefox -P` or something like that) to see if this issue remains.

What happens if you use our GitLab mirror (which uses Doxygen 1.9.4)? Do you have the same issues?

If this all doesn't help, can you tell us which browser and version you are using, and which personal settings (themes, addons) that might be relevant?

I'm not sure if we could change anything if it's not your specific user setting because we're using the default Doxygen layout settings. Admittedly the chosen colors look a bit strange (even in my screenshot) and we could change the design anyway, but that's another topic.

[Mo_Al_]

The gitlab index https://fltk.gitlab.io/fltk/index.html shows a light theme.

I previously tried with chrome and now with firefox, and the 1.9.8 version shows a dark theme as well by default. It seems because my machine (windows 11) uses dark mode, so the browsers also default to it. 
It also seems there is no way to change to a light theme in the doxygen generated page. 

[Mo_Al_]

The only way I could change to light was using the developer console by changing the css prefers-color-scheme to light instead of dark. 

Although I would personally prefer the dark theme, save for the index appearance.

Trying the suggestions here:

https://github.com/doxygen/doxygen/issues/10177

the ESC key doesn't toggle light/dark, and there's no sun icon which one can click.

[Albrecht Schlosser]

On 9/4/23 14:21 Mo_Al_ wrote:

The only way I could change to light was using the developer console by changing the css prefers-color-scheme to light instead of dark. 

Although I would personally prefer the dark theme, save for the index appearance.

Trying the suggestions here:

https://github.com/doxygen/doxygen/issues/10177

We're using the default values of almost all Doxygen parameters, of course except those we need to set to find the source files, set the title, etc.. Therefore, we have 'HTML_COLORSTYLE = AUTO_LIGHT' in our "Doxyfile".

I set it to "DARK" and I can see the same colors and the contrast issue you're seeing.

An option would be to set explicitly it to "LIGHT" but then users with a system set to "dark mode" (like you) would see the normal "light" colorstyle in our docs. For now this looks like the way with the least resistance. However, there's an issue that needs investigation: the parameter 'HTML_COLORSTYLE' seems to be a recent addition, hence it doesn't exist in our Doxygen template. I'll check how we can use this in the future.

Thanks for pointing this out and the link to the Doxygen issue. This was very helpful.

the ESC key doesn't toggle light/dark, and there's no sun icon which one can click.

Same here. I don't have a search field either where this sun icon should be located according to the issue mentioned above. As I said, this would need more investigation.

On Monday, September 4, 2023 at 3:12:20 PM UTC+3 Mo_Al_ wrote:

The gitlab index https://fltk.gitlab.io/fltk/index.html shows a light theme.

I previously tried with chrome and now with firefox, and the 1.9.8 version shows a dark theme as well by default. It seems because my machine (windows 11) uses dark mode, so the browsers also default to it. 
It also seems there is no way to change to a light theme in the doxygen generated page. 

On Monday, September 4, 2023 at 3:01:38 PM UTC+3 Albrecht Schlosser wrote:

On 9/4/23 13:40 Mo_Al_ wrote:

The theme is much better than the old one.

Thanks for your comments.

I noticed that the index page has some color issues:

Hmm, you seem to use a "dark theme" or some other personal browser settings. I can't reproduce this here:



Even if I change Firefox to use a dark theme, the contents stay the same.

Maybe you need to refresh the entire browser window (use Shift+RefreshButton) or you have some other issues with your browser. You could also try to use Firefox with a new profile (run `firefox -P` or something like that) to see if this issue remains.

What happens if you use our GitLab mirror (which uses Doxygen 1.9.4)? Do you have the same issues?

If this all doesn't help, can you tell us which browser and version you are using, and which personal settings (themes, addons) that might be relevant?

I'm not sure if we could change anything if it's not your specific user setting because we're using the default Doxygen layout settings. Admittedly the chosen colors look a bit strange (even in my screenshot) and we could change the design anyway, but that's another topic.

--
You received this message because you are subscribed to the Google Groups "fltk.coredev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fltkcoredev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/fltkcoredev/a0cb384a-bf54-40f5-86bd-142fa16239e4n%40googlegroups.com.

[Albrecht Schlosser]

On 9/4/23 17:37 Albrecht Schlosser wrote:

We're using the default values of almost all Doxygen parameters, of course except those we need to set to find the source files, set the title, etc.. Therefore, we have 'HTML_COLORSTYLE = AUTO_LIGHT' in our "Doxyfile".

I set it to "DARK" and I can see the same colors and the contrast issue you're seeing.

An option would be to set explicitly it to "LIGHT" but then users with a system set to "dark mode" (like you) would see the normal "light" colorstyle in our docs. For now this looks like the way with the least resistance. However, there's an issue that needs investigation: the parameter 'HTML_COLORSTYLE' seems to be a recent addition, hence it doesn't exist in our Doxygen template. I'll check how we can use this in the future.

OK, a quick check shows that we can set it in our "old" (1.5.5) version of Doxyfile.in and it survives the conversion to the current Doxygen version (1.9.8) which is done during the generation process. Here's a patch:
```

$ git diff
diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in
index 57e49934d..dea1c6484 100644
--- a/documentation/Doxyfile.in
+++ b/documentation/Doxyfile.in
@@ -10,6 +10,16 @@
 #       TAG += value [value, ...]
 # Values that contain spaces should be placed between quotes (" ")
 
+### begin 'HTML_COLORSTYLE' hack ###
+
+# Presumably added in Doxygen 1.9.x, default value: 'AUTO_LIGHT'.
+# We need to set it explicitly to "LIGHT", otherwise our title page
+# can become unreadable for users on a "dark mode" system setup.
+
+HTML_COLORSTYLE        = LIGHT
+
+### end of 'HTML_COLORSTYLE' hack ###
+
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------

```

If you can (and want to) create the doxygen docs yourself it would be great if you could test this patch. Make sure that you use a fresh checkout or at least a clean 'documentation' directory if you're using CMake.

Something like this worked for me on my Linux system:

$ cd <fltk-cmake-build-dir>
$ rm -rf documentation
$ ninja clean rebuild_cache
$ ninja html

I'm using `ninja`, YMMV. Note that documentation generation (certainly the PDF docs) does not work on Windows if you build with VS. It *may* work with MinGW/MSYS2 if you have the necessary tools installed. Generation of HTML docs might be much easier.

[Mohammed]

Thank you. I got a bit busy. I’ll try the patch hopefully tomorrow. 

Sent from my iPhone

On 4 Sep 2023, at 18:59, Albrecht Schlosser <Albrech...@online.de> wrote:



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

To view this discussion on the web visit https://groups.google.com/d/msgid/fltkcoredev/393748ba-bcf2-c9e5-e88c-b8a2b573e4dc%40online.de.

[Albrecht Schlosser]

On 9/4/23 22:47 Mohammed wrote:

Thank you. I got a bit busy. I’ll try the patch hopefully tomorrow.

That would be great, thanks in advance. Meanwhile I also set 'HTML_COLORSTYLE = TOGGLE' and I got indeed the "sun" icon and can now switch between dark mode and light mode with a click:



Can you please test this as well and report whether you get the dark mode or the light mode when you launch firefox or other browsers on your "dark mode" system, and of course if switching the mode works on your system? Please tell us also which browser(s) you are using and any differences per browser.

On 4 Sep 2023, at 18:59, Albrecht Schlosser wrote:

OK, a quick check shows that we can set it in our "old" (1.5.5) version of Doxyfile.in and it survives the conversion to the current Doxygen version (1.9.8) which is done during the generation process. Here's a patch:

[Mo_Al_]

Hi

I've tried with the patch. It seems the browser just ignores HTML_COLORSTYLE = LIGHT. 

I've tried switching it to TOGGLE and I now get the sun toggle button:

I tried with doxygen 1.9.8 then with 1.10.0 (built from master). Same behavior.

[imacarthur]

FWIW, just for info., with Chrome or Edge, with the "dark" theme selected at system level on Win10 and Win11 I see the "unfortunate" colour contrast effect Mo reports when I browse the docs online. There is no "sun" button, and the "esc key" trick does not work.

Locally built, the docs are "light", presumably because I only have doxygen-1.8.16 so it is not getting all the new colour settings? I tried adding 'HTML_COLORSTYLE = TOGGLE'  to my doxygen file, but that just threw a (non fatal) warning at build time and did nothing else (as expected).

 

[Albrecht Schlosser]

On 9/5/23 13:47 Mo_Al_ wrote:
> I've tried with the patch. It seems the browser just ignores
> HTML_COLORSTYLE = LIGHT.

Thanks for testing. I don't think the browser is directly involved in
"ignoring" HTML_COLORSTYLE = LIGHT. Doxygen (likely > 1.9.6 but maybe
earlier - not yet checked by me) converts this to some CSS settings
which the browser then uses. Maybe you didn't purge the old doc
generation (as I posted in my previous post)?

> I've tried switching it to TOGGLE and I now get the sun toggle button:

OK, that's great.

What is the initial appearance when you open the docs with your browser
for the first time? Is it honoring your system setting (dark mode) or is
it showing the light mode?

> I tried with doxygen 1.9.8 then with 1.10.0 (built from master). Same
> behavior.

OK, thanks for this as well. FYI: I'm building new doxygen versions from
sources (from time to time), using the Git release tags, i.e. I'm only
using released versions (not git master) but I could try this as well
when needed.

@Mo_Al_ : what would be your suggestion - should I use 'HTML_COLORSTYLE
= LIGHT' or 'HTML_COLORSTYLE = TOGGLE' for the next doc upload?

[Albrecht Schlosser]

On 9/5/23 14:34 imacarthur wrote:

FWIW, just for info., with Chrome or Edge, with the "dark" theme selected at system level on Win10 and Win11 I see the "unfortunate" colour contrast effect Mo reports when I browse the docs online. There is no "sun" button, and the "esc key" trick does not work.

Ian, thanks for testing and your feedback.

The current online docs have been generated with Doxygen 1.9.8 using the default 'HTML_COLORSTYLE = AUTO_LIGHT' which obviously selects dark mode automatically on a system that's set up to use dark mode. Your observation confirms this.

Locally built, the docs are "light", presumably because I only have doxygen-1.8.16 so it is not getting all the new colour settings?

Yes, exactly. 1.8.16 is too old, 'HTML_COLORSTYLE' has been introduced in 1.9.5 (just checked the changelog).

I tried adding 'HTML_COLORSTYLE = TOGGLE'  to my doxygen file, but that just threw a (non fatal) warning at build time and did nothing else (as expected).

Correct.

FYI: FLTK's doxygen generation process converts our very old (intentional: 1.5.5) 'Doxyfile.in' file (with some manual edits) to the doxygen version in use by the process (for both HTML and PDF docs). You can find these converted files (Doxyfile and Doxybook, resp.) in the documentation directory, either in the source tree (configure/make) or in the build tree (CMake).

If you add an unknown tag to your Doxyfile and run `doxygen` then doxygen issues a warning as you noticed. The trick to "update" Doxyfile.in to the used doxygen version (`doxygen -u -s`) prevents such warnings. At least that was my intention.

Now, if we add 'HTML_COLORSTYLE = TOGGLE' or 'HTML_COLORSTYLE = LIGHT' to our 'Doxyfile.in' and "update" this file directly to 1.9.8 this line is kept by the conversion process, but if you build with 1.8.16 instead the update process eliminates all unknown doxygen tags (silently). That's what I was trying to achieve. Of course, if you build with 1.8.6 there are no new features that were added in 1.9.5.

I'm thinking about adding either 'HTML_COLORSTYLE = TOGGLE' or 'HTML_COLORSTYLE = LIGHT' to our 'Doxyfile.in' which should supposedly "work" with any doxygen version with different outcome. If we used 'LIGHT' users of dark mode systems would always get the light version. If we used 'TOGGLE' some users would see the 'dark' version but could switch to the light version with the 'sun' toggle button. The question is, which one to use. Another option would of course be to change our colors to be usable with both the dark and the light mode.

Any suggestions?

PS: our GitLab mirror CI build which generates the docs at https://fltk.gitlab.io/fltk/ still uses 1.9.4 unfortunately, which has some layout issues (see "Class Index": https://fltk.gitlab.io/fltk/classes.html ). However, we can't change this and at some time in the future they will certainly update the CI machine to a newer Doxygen version (they did this previously from 1.9.1 to 1.9.4). This bad layout was fixed Doxygen 1.9.5 or 1.9.6.

[Mo_Al_]

I'm not sure. I try to reload with ctrl + enter and it normally works, like with the toggle for example. 

Personally I would prefer the toggle option since I prefer dark mode. 

I'm inclined to suggest changing the colors in documentation/src/index.dox, the colors there are quite close to each other:

#9f9fef and #9f9f9f

[Mo_Al_]

here I just removed the colors:

[Albrecht Schlosser]

On 9/5/23 17:02  Mo_Al_ wrote:
> here I just removed the colors: (image removed)

Thanks for your info. And your patch (diff) is ... ?

I removed all three "BGCOLOR="#9f9f*" statements which made the
background white in the normal (light) mode and seems to have good
contrast in both modes. Since I used the "TOGGLE" mode it's easy to
switch light/dark in the browser.

I think this is the way to go until we decide to use a better design.
I'll do more tests and I believe I can update the sources tomorrow. If
everything works out well I'll upload a new version to our FLTK server
and let you know.

See my preliminary patch attached.

Thanks for your assistance, I appreciate this very much.

PS: (@Mo_Al_) I'm currently finalizing Fl_Grid to add this new widget to
FLTK/Git. I assume this will be ready during the next three days.
Hopefully. Please watch the commits if you like to update your fltk-rs
port, but please be aware that whatever is committed next may not be the
final solution (even API changes may still happen until we release 1.4.0).

[Mohammed]

Thanks Albrecht for the heads up. I can add Grid under an experimental feature or with a "hidden" doc attribute, this allows breaking changes without semver violation according to Rust’s package management system I believe.

Sent from my iPhone

> On 5 Sep 2023, at 23:36, Albrecht Schlosser <Albrech...@online.de> wrote:

> --
> You received this message because you are subscribed to the Google Groups "fltk.coredev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to fltkcoredev...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/fltkcoredev/2682ebad-3583-163c-de1b-a922c7e00cdc%40online.de.
> <doxygen_dark_mode.diff>

[Albrecht Schlosser]

On 9/5/23 22:36 Albrecht Schlosser wrote:
> I removed all three "BGCOLOR="#9f9f*" statements which made the
> background white in the normal (light) mode and seems to have good
> contrast in both modes. Since I used the "TOGGLE" mode it's easy to
> switch light/dark in the browser.
>
> I think this is the way to go until we decide to use a better design.
> I'll do more tests and I believe I can update the sources tomorrow. If
> everything works out well I'll upload a new version to our FLTK server
> and let you know.

Done in commit f5afea3421ea68899d3064b09184c29f30ce0588.

The new docs are now online. Changes are:

- White background on title page in light mode
- Mode switch enabled ("TOGGLE" mode)
- Search engine enabled

The generation process has also been modified but this has nothing to do
with the online docs.

Enjoy!

Feedback would be appreciated.

[imm]

FWIW, looks OK in my tests. "Dark" mode is now readable.
And I think I quite like the plain white background (in "light" mode)
even though it is a change...

[Albrecht Schlosser]

On 9/8/23 10:21 imm wrote:
> FWIW, looks OK in my tests. "Dark" mode is now readable.

Thanks for testing again.

> And I think I quite like the plain white background (in "light" mode)
> even though it is a change...

So do I. I never liked the "FLTK blue" color much, and it's also looking
pretty unusual on our web site.

In the docs where it was *only* the title page I believe the change is
an improvement.

[Mo_Al_]

Sorry forgot to check the updated docs. Both light and dark look nice, and the index is readable in dark mode.

[Albrecht Schlosser]

On 9/9/23 14:08 Mo_Al_ wrote:
> Sorry forgot to check the updated docs.

No problem.

> Both light and dark look nice, and the index is readable in dark mode.

Great, then that's what we'll keep now.