Character encoding issues in manual

[pviotti]

Some characters in the manual are badly rendered.

etc.

v1.2.8 on Windows and Linux.

[lupino3]

Thanks @pviotti! Curiously enough, it all seems ok on readthedocs: https://edumips64.readthedocs.io/en/latest/

[lupino3]

Also works on Mac OS X

[lupino3]

The issue is visible even for the JAR built by CI (just excluding a possible misconfiguration of my local desktop where I built the JAR)

[lupino3]

Broken even in 1.2.7:

[lupino3]

1.2.6 looks better, so the breakage is likely to have happened between 1.2.6 and 1.2.7:

[lupino3]

BTW 1.2.8 does not look broken to me on Ubuntu 20.04

@pviotti what version of Linux are you using?

[pviotti]

Arch :) but there's nothing special about its package, AFAIK. I tried to reinstall previous versions and, as you wrote, 1.2.7 has the same issue, 1.2.6 doesn't. From a quick look at the history the issue might have been introduced by one of these commits:
65424f4
e343883
0f246d1
4d404c7
e1c678f

Javahelp is not maintained anymore, so if this proves difficult to fix it'd be an opportunity to get rid of it (maybe just embedding HTML into the jar and launching a browser would do - though I'm not sure how exactly..).

[lupino3]

That's a good point, we aren't really using many JavaHelp features. Maybe we could try a JavaFX WebView: https://stackoverflow.com/questions/13487786/add-webview-control-on-swing-jframe

[lupino3]

Just for the record, I tried an old version of Sphinx (2.3.1) but that was not the issue.

I thought a bit about it, and the alternatives to JavaHelp are not great:

1. JavaFX has good rendering but has hundreds of MBs of dependencies and, more importantly, makes it much harder to create a cross-platform JAR;
2. JEditorPane is very primitive and has the same rendering issues that JavaHelp has
3. FlyingSaucer renders as an image, which is not selectable and not searchable.

I currently lean towards

1. trying to fix JavaHelp
   1a) possibly see if it would be possible to use JEditorPane instead of JavaHelp, which would get rid of the JavaHelp dependency while providing similar features.
2. in parallel also providing the new feature of opening the manual in an external browser as a fallback, via a separate menu option.

@pviotti what do you think?:

[pviotti]

trying to fix JavaHelp

you mean poking around JavaHelp code and try to see if there's an easy way to fix encoding issues? That can be done, and maybe it would be useful to other projects too, though it can take a long time (if it's possible at all).
The alternative are not great, indeed (I'm particularly surprised that JEditorPane has encoding and graphics glitches even in the latest JRE versions 😕)

If you really want to avoid depending on browsers, I suspect it would be easier to embed the documentation in some other format, like PDF.

[lupino3]

I meant try to understand where we introduced the regression: 1.2.6 works well and 1.2.7 doesn't -- I'd like to pinpoint what commit introduced the encoding issues and see if that's fixable.

But the PDF idea is also very good, I'll have a look around to see if there are any Swing PDF viewers. A very quick search yielded this library, which I'll now try out: https://mvnrepository.com/artifact/org.icepdf.os/icepdf-core/6.1.2

[lupino3]

I tried to use icepdf but the artifacts on the Maven repos do not work due to broken dependencies.

The website doesn't mention Maven and the download of the open source JAR is behind a login form: http://www.icesoft.org/java/home.jsf

I found a fork which seems maintained but it's not yet published to a Maven repo. I asked them if they will publish it here: pdf4j/icepdf#7

[lupino3]

Well the fork is not really maintained, I got confused with another repo I was looking at.