Try switching Georgia (vs Goudy Old Style) to be explicit first font choice

[FichteFoll]

I find the typeface to be too thin for continuous pleasant reading and would consider something akin to Georgia (which Flask uses for example) to be better. It's also bigger, but the typeface definitely plays a larger role.

I suggest opening the images in new tabs for optimal viewing (github resized them).

source: http://docs.python-requests.org/en/master/

source: http://flask.pocoo.org/docs/0.10/errorhandling/

[kennethreitz]

You know, on all my machines, I only see this theme with Georgia as the body text. I wasn't aware until recently that others don't also see it this way (on Windows it renders with italics sometimes, for some reason). I want to fix this.

Georgia looks much better, and was what I intended the body font to be. I would be +10 to an update.

[kennethreitz]

p.s. that's how it's always looked on my machines.

[FichteFoll]

I wasn't aware until recently that others don't also see it this way (on Windows it renders with italics sometimes, for some reason). I want to fix this.

As an addition to this, I had the problem of FireFox choosing the italics variant of Goudy Old Style on my machine. The regular variant was clearly installed on my system and it worked in Chrome. I eventually "fixed" the issue by disabling hardware acceleration in FireFox, but until then the issue was even worse.

Edit: Added sources to the images for better "reproduction".

[bitprophet]

I see it as Georgia too, for the record. Also +1 on tweaking things so it's intentionally Georgia by default.

Main problem is backwards compatibility, I wonder how many people are seeing Old Goudy and do like it.

[kennethreitz]

@bitprophet I think it's safe for us to consider any users seeing it as Old Goudy now as a bug. In the very unlikely event of user backlash over greatly improved typography and text-legibility, we could cut a release that makes this preference configurable (I'd much prefer not to do that though).

[FichteFoll]

It already is configurable (in conf.py). This is really just about the default.

[bitprophet]

Current font theme conf is https://github.com/bitprophet/alabaster/blob/64aa6ddcc8d3f5c40dfe5b9eca46abdbe5b53a99/alabaster/theme.conf#L65 - so question to me is, should we not only remove the 1st entry (goudy old style) but also shift Georgia so it's first? Makes it more explicit that we expect the default view for most users to be Georgia.

I suppose we could leave minion pro and bell mt in the list at 2nd and 3rd place? Depends a lot on who added them originally and why. Guessing they're from Armin's lineage if Kenneth didn't even know Goudy was in here? :D

[FichteFoll]

Minion Pro is almost as thin as Goudy Old, so it disqualifies as being on that list entirely as well, imo.

Bell MT works. It's similar to Georgia but a bit smaller (at least for me) and reads nicely.

However, I'm +1 for moving Georgia to the front just because it will mean that more (probably all) people are going to see the text in the same way with the same type face and, also regarding my description of Bell MT, it's much more easier to tweak font size that way. It's better for compatibility.

[segevfiner]

I'm on Windows 7 SP1 64-bit and Goudy Old Style displays in italic (Goudy Old Style Italic) in both the latest Firefox and IE. It displays correctly in Chrome. This makes it quite hard to read and makes emphasis indistinguishable from normal body text.

It would really be nicer if this theme used "safer" fonts or "@font-face" so that it displays the same in all browsers and operating systems.

[kennethreitz]

I can confirm that the font is indeed italics on Edge on Windows 10.

[kennethreitz]

However, it doesn't look bad!

[bitprophet]

Also we never linked this to #37 which is another font related ticket (about adding webfont support for Garamond which apparently also looks better than Goudy.) Feel like they might be slightly exclusive with each other, needs more examination.

[hynek]

Ehm this would also fix #100. :)

[bitprophet]

@hynek But it could easily pull the rug out from under anyone who's currently seeing Goudy by default :( so far #100 still isn't affecting tooo many people?

That said we have other kinda-backwards-incompat changes in the pipe (eg dropping 2.6 support via #121 and related) so once I A) have time and B) figure out the least crap way to get out a "breaking" release and communicate it correctly to Sphinx's setup.py, yea, we can hopefully make this change.

[hynek]

May I suggest something like Palatino, Cambria, Droid Serif, Georgia, serif if you pull any rugs? :) That gives you good, readable serif fonts on macOS/iOS, “modern” Windows and Android. (sorted by conflict likeliness)

[kennethreitz]

@hynek can you send a screenshot?

[kennethreitz]

Font names are useless to me, only appearances matter.

[kennethreitz]

Palatino should not be first, in my opinion. Old Goudy should be preferred before it.

[kennethreitz]

Palatino looks nice, but is a fallback for a reason.

[kennethreitz]

It's a bit harsh looking, in comparison to Goudy, which has more of a "hand crafted feel", which the theme intends to convey if possible to reader.

[kennethreitz]

I vote for leaving things as-is. While not always consistient, we have a nice order preserved at the moment, and different readers get different experiences based on what typefaces they have installed (e.g. how much they value typography). I think there's value in that.

Uniformity in presentation should not be the goal, is my proposal.

[kennethreitz]

e.g. The variance in font presentation between machines has always been a feature to me, not a bug.

[kennethreitz]

I have Adobe Creative suite installed, as well as some specific typefaces that @mitsuhiko uses that I use for my keynotes/presentations, so my presentation always looks like this:

I love this presentation, and when I see it looking otherwise on another machine, I am also thrilled, because it looks nice there as well, and is refreshing.

[kennethreitz]

I think the proper solution here, if we do want to strive for uniformity, is to rely on a Google Font, which I would chose, for the body of the content. Would anyone be against this?

I'd be happy to take some serious time to select an appropriate typeface that reflects the essence of this theme and everything it represents.

---

Or, we leave things as-is.

[kennethreitz]

I have a deep passion for typography, hence me proposing that I take up the task of selecting a suitable all-encompasing typeface for the theme.

[kennethreitz]

I may be incorrect in thinking so, but I think this is perfectly appropriate and not doing so over 40KB is making the many suffer for the slight inconvenience of the few.

[kennethreitz]

Keep in mind, I also embed 1.4MB images on all of my documentation pages, and have received 0 complaints so far for doing so. People with slow connections are patient people, and are used to sub-optimal web experiences. 40KB is going to be relatively fast, even over EDGE.

[hynek]

Well, this ticket was open because Goudy is hard to read so it’s hard to tell which alternative means suffering. :)

[kennethreitz]

And if read the docs doesn't do e-tags for static assets, I'm sure we can convince them to in a 10 minute conversation :)

I'm pretty confident they do, though.

[kennethreitz]

Gaudy bookletter 1911, the intended Gaudy, is not hard to read. Adobe's is.

[kennethreitz]

I'm speaking authoritatively because Alabaster is based on my work, as the documentation states (and, of course, the work of @mitsuhiko). I'm also stating, that if the project desires to continue in that lineage then moving to Palatino would be a step in the wrong direction.

[kennethreitz]

As a first step, we could fix the font family name in the CSS from "gaudy" to "gaudy bookletter". that would resolve @hynek's problem.

We could then evaluate unifying the user experience later, though embedding a web font or otherwise.

Bear in mind, Sphinx search for a documentation site involves loading a JSON doc far larger than 40KB typically.

[FichteFoll]

Gaudy bookletter 1911 does indeed look better than the Goudy Old Style screenshot I included in the OP.

Currently, I have Minion Pro rendering on the requests docs (actually, Minion Pro-Bold because apparently I don't have the regular variant – looks quite bad):

I don't care whether a webfont is provided or not, although reasonable fallbacks must be present. NoScript, for example, blocks webfonts by default.

---

Generally I find sans serif fonts much more pleasant to read on displays due to the limited dpi. I do not have a 4k display and you shouldn't assume everyone to have one.
Have you considered using a sans-serif font instead of serif?

[bitprophet]

I'm generally in favor of a minimal change first, if we can prove that just tweaking the font names a bit is sufficient to head off the "ew, italics" problem (hopefully via @hynek as guinea pig, I dunno how annoying it is for him to perform the system-level font changes that he is using as workaround!)

Re: web fonts and/or embedded fonts, I'm on the fence (all else equal, I don't want to lessen the experience for mobile or non-US/EU users) though I'll also note that in #37, the typically picky @alex also suggested use of a web font.

---

It sounds like the recommended change at this point is, what, sticking goudy bookletter in front of goudy old style? Perhaps simply replacing the latter with the former?

Might be nice to roll up some (internal, external, doesn't matter) documentation about which fonts in our list are available on what default OS installs and/or via common software packages. Just so users who run into this same "wha? it looks bad!!" issue have some frame of reference.

[kennethreitz]

+1 to Georgia as being first place.

[willingc]

Thanks @hynek, @kennethreitz, and @bitprophet for finally helping me figure out why the rendering on Safari was not consistent with what I was seeing on Chrome. I happen to also fall into the "ew" italics. For weeks, it has been bugging me, and now I know why ;-)

P.S. Thanks for your work on the theme too 🌻

[nogweii]

Another "ew, italics" here. For whatever reason Firefox on Windows 10 will prefer the Italics over Regular style Goudy Old Style font, so it's somewhat hard to tell what is supposed to be emphasized in the document or not: https://screenshots.firefox.com/RzQW5iarsVSDEKWC/docs.alerta.io

Love the rest of the theme! (And looks great on Linux, funnily enough.)

[FichteFoll]

@evaryont as I mentioned above, try disabling hardware acceleration within FF. I'm not sure if this has changed since FF57 since I don't use Windows anymore, but that's what helped me previously.

That's only a workaround, of course.

[goerz]

I'm still seeing the unreadable italic Goudy Old Style font as in @hynek's screenshot. I have to say, considering that this is now the default Sphinx theme, I'm quite flabbergasted that this issue (and #100, which should not be closed) remains unresolved for over a year. Not having broken fonts for a large number of users seems like it should be a top priority, even if the broken rendering is somehow "not your fault". If Goudy is known not to work for a significant number of users, it should not be part of any theme!

[FichteFoll]

Since apparently it doesn't seem like it has been mentioned explicitly before, I'm highly in favor of removing Goudy Old Style from the font list altogether. As long as it remains there, the italics rendering (also in #100) is a possibility in case any of the earlier fonts are not available, which disqualifies it from being chosen at all even as a fallback.

Currently, the request docs look so ugly to me (see my latest screenshot) that the next time I need to use them I'll probably end up defining a local style override and have it pick a sans-serif font instead. This isn't entirely your fault, since it's unusual to only have a bold variant of a font face installed, but the fact that it looks so different on many machines is your fault because you don't consider compatibility through font availability. Or at least you haven't changed anything in two years since I reported the issue.

[bitprophet]

Hynek will fold me in two if I don't solve this at sprints and I've been meaning to tackle it anyways.

One issue is that of backwards compat, as mentioned much earlier, but from the historic discussion it sounds like there's almost nobody actually seeing Goudy. I certainly aren't (inspector says I'm getting Georgia) and I consider my install to be relatively mainline (macOS, Chrome, no extra fonts installed, no Adobe apps installed, etc).

So we can definitely go ahead with this in an 0.7.x release. I just gotta reread all this to see what the consensus was on exactly how to do it: just remove Goudy; move Goudy around; choose an alternate Goudy (but also probably move it around); etc.

[bitprophet]

Also, I do want to say I don't appreciate @FichteFoll's snarky attitude 😛 Yea, it's my fault. Yea I haven't solved it in a few years because it doesn't impact me personally and it still sounds like it "only" affects a minority of users. (Quotes because it's certainly not a vanishingly small one.)

You can have your money back if you'd like 😁

[bitprophet]

Yea sounds like just nuking Goudy is the best way forwards. If we inexplicably get folks complaining that they REALLY WANTED Goudy, they can simply do what everyone impacted by this issue is presumably doing - set their own font_family theme option override.

[willingc]

Thanks @bitprophet. Appreciate your work on this theme. The JupyterHub team loves Alabaster.

[bitprophet]

Also Hynek continues to whisper in my ear that other fonts in our list are frequently Adobe only. Given the high level of control and infrequent distribution of many fonts, it might make sense to just pare it down to Georgia, serif.

And to also alter head_font_family to match - I get the original conceit of "have different font for the headers" - but that's Garamond right now which is another Adobe-only font face apparently. So e.g. I have never really seen the dual-font version of the theme on my own systems.

[FichteFoll]

Thanks for looking into this and removing the problematic fonts.

I know I've been a bit snarky in my comment, but it was a conscious decision as I didn't see any other way to motivate you to look into it. (And after reading Kenneth's comments again it felt like I had to stress very explicitly that his proposals do not solve the issue.)
It's an extremely frustrating issue once you are affected by it and I wanted to share the frustration with someone who isn't. I hope you can understand and sorry for resorting to this measure.

[willingc]

I know I've been a bit snarky in my comment, but it was a conscious decision as I didn't see any other way to motivate you to look into it.

While I can understand frustration, being snarky, especially as a conscious choice, isn't a thoughtful motivator for volunteer maintainers. At PyCon this year, Brett Cannon gave a wonderful talk about communication between maintainers and users: https://youtu.be/tzFWz5fiVKU?t=49m23s It's worth watching if you haven't seen it.

[goerz]

@bitprophet Thank you for your great work! I'm sorry for having been unnecessarily harsh on this thread. It wasn't meant as a personal criticism.

[bitprophet]

Apologies for not actually kicking this out the door once we tackled it at sprints! I just bundled it and all of its "hanging out in master, bored as heck" friends into 0.7.11 and it's on PyPI.

[hynek]

JFTR https://alabaster.readthedocs.io/en/latest/customization.html#fonts needs to be adapted to the new defaults

[bitprophet]

Ugh I forgot we repeat a lot of the defaults there. Wonder why I did that, usually I'm severely allergic to that sort of repetition. Thanks @hynek ! Will fix. EDIT: fixed: 33b4b20